FunctionInfo.h

Go to the documentation of this file.

//===----- FunctionInfo.h - ABI Function 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
//
//===----------------------------------------------------------------------===//
//
// Defines FunctionInfo and associated types used in representing the
// ABI-coerced types for function arguments and return values.
//
//===----------------------------------------------------------------------===//
 
#ifndef LLVM_ABI_FUNCTIONINFO_H
#define LLVM_ABI_FUNCTIONINFO_H
 
#include "llvm/ABI/Types.h"
#include "llvm/ADT/ArrayRef.h"
#include "llvm/IR/CallingConv.h"
#include "llvm/Support/Alignment.h"
#include "llvm/Support/Casting.h"
#include "llvm/Support/TrailingObjects.h"
#include <optional>
 
namespace llvm {
namespace abi {
 
/// Helper class to encapsulate information about how a specific type should be
/// passed to or returned from a function.
class ArgInfo {
public:
  enum Kind {
    /// Pass the argument directly using the normal converted LLVM type, or by
    /// coercing to another specified type stored in 'CoerceToType'.
    Direct,
    /// Valid only for integer argument types. Same as 'direct' but also emit a
    /// zero/sign extension attribute.
    Extend,
    /// Pass the argument indirectly via a hidden pointer with the specified
    /// alignment and address space.
    Indirect,
    /// Like Indirect, but the pointer may alias an object referenced
    /// elsewhere. The callee must not modify it and never treats it as byval.
    IndirectAliased,
    /// Ignore the argument (treat as void). Useful for void and empty structs.
    Ignore,
 
    /// Only valid for aggregate argument types. The value is expanded into
    /// one argument per non-padding element of CoerceToType. Arrays of i8 are
    /// assumed to be padding.
    CoerceAndExpand,
  };
 
private:
  const Type *CoercionType = nullptr;
  const Type *UnpaddedCoerceAndExpandType = nullptr;
  // Alignment is optional for direct arguments, but required for indirect
  // arguments. This invariant is enforced by the methods of this class.
  //
  // The field is not part of DirectAttrInfo/IndirectAttrInfo because it would
  // make the union non-trivial, disabling implicit copy/move constructors and
  // assignment operators for the entire class.
  MaybeAlign Alignment;
 
  struct DirectAttrInfo {
    unsigned Offset;
  };
 
  struct IndirectAttrInfo {
    unsigned AddrSpace;
  };
 
  union {
    DirectAttrInfo DirectAttr;
    IndirectAttrInfo IndirectAttr;
  };
 
  Kind TheKind;
  bool SignExt : 1;
  bool ZeroExt : 1;
  bool IndirectByVal : 1;
  bool IndirectRealign : 1;
  bool CanBeFlattened : 1;
  unsigned NeededIntRegs : 3;
  unsigned NeededSseRegs : 3;
 
  ArgInfo(Kind K = Direct)
      : TheKind(K), SignExt(false), ZeroExt(false), IndirectByVal(false),
        IndirectRealign(false), CanBeFlattened(false), NeededIntRegs(0),
        NeededSseRegs(0) {}
 
public:
  /// \param T The type to coerce to. If null, the argument's original type is
  ///          used directly.
  /// \param Offset Byte offset into the memory representation at which the
  ///               coerced type begins. Used when only part of a larger value
  ///               is passed directly (e.g. the high word of a multi-eightbyte
  ///               return value on x86-64).
  /// \param Align  Override for the argument's alignment. If absent, the
  ///               default alignment for \p T is used.
  /// \param CanBeFlattened Whether a record coercion may be split into one
  ///               wire argument per field. See getCanBeFlattened.
  static ArgInfo getDirect(const Type *T = nullptr, unsigned Offset = 0,
                           MaybeAlign Align = std::nullopt,
                           bool CanBeFlattened = true) {
    ArgInfo AI(Direct);
    AI.CoercionType = T;
    AI.Alignment = Align;
    AI.DirectAttr.Offset = Offset;
    AI.CanBeFlattened = CanBeFlattened;
    return AI;
  }
 
  static ArgInfo getExtend(const Type *T) {
    assert(T && "Type cannot be null");
    assert(T->isInteger() && "Unexpected type - only integers can be extended");
 
    ArgInfo AI(Extend);
    AI.CoercionType = T;
    AI.Alignment = std::nullopt;
    AI.DirectAttr.Offset = 0;
 
    const IntegerType *IntTy = cast<IntegerType>(T);
    if (IntTy->isSigned())
      AI.setSignExt();
    else
      AI.setZeroExt();
 
    return AI;
  }
 
  /// Realign: the caller couldn't guarantee sufficient alignment - the callee
  /// must copy the argument to a properly aligned temporary before use.
  static ArgInfo getIndirect(Align Align, bool ByVal, unsigned AddrSpace = 0,
                             bool Realign = false) {
    ArgInfo AI(Indirect);
    AI.Alignment = Align;
    AI.IndirectAttr.AddrSpace = AddrSpace;
    AI.IndirectByVal = ByVal;
    AI.IndirectRealign = Realign;
    return AI;
  }
 
  /// An aliased indirect argument. It carries an address space but no byval,
  /// since the pointer refers to an object the caller owns.
  static ArgInfo getIndirectAliased(Align Align, unsigned AddrSpace,
                                    bool Realign = false) {
    ArgInfo AI(IndirectAliased);
    AI.Alignment = Align;
    AI.IndirectAttr.AddrSpace = AddrSpace;
    AI.IndirectRealign = Realign;
    return AI;
  }
 
  static ArgInfo getIgnore() { return ArgInfo(Ignore); }
 
  /// \param CoerceToType Aggregate type whose non-padding elements are the
  ///        in-memory pieces of the value, in order. Padding elements are
  ///        arrays of i8.
  /// \param UnpaddedCoerceToType \p CoerceToType with padding elements
  ///        removed. A single element is stored as that element; two or more
  ///        are a packed record.
  static ArgInfo getCoerceAndExpand(const Type *CoerceToType,
                                    const Type *UnpaddedCoerceToType) {
    assert(CoerceToType && UnpaddedCoerceToType &&
           "coerce-and-expand types cannot be null");
    assert(isa<RecordType>(CoerceToType) &&
           "coerce-and-expand coerce type must be a record");
    ArgInfo AI(CoerceAndExpand);
    AI.CoercionType = CoerceToType;
    AI.UnpaddedCoerceAndExpandType = UnpaddedCoerceToType;
    return AI;
  }
 
  ArgInfo &setSignExt(bool SignExtend = true) {
    this->SignExt = SignExtend;
    if (SignExtend)
      this->ZeroExt = false;
    return *this;
  }
 
  ArgInfo &setZeroExt(bool ZeroExtend = true) {
    this->ZeroExt = ZeroExtend;
    if (ZeroExtend)
      this->SignExt = false;
    return *this;
  }
 
  /// See getCanBeFlattened.
  ArgInfo &setCanBeFlattened(bool Flatten) {
    assert(isDirect() && "Invalid Kind!");
    CanBeFlattened = Flatten;
    return *this;
  }
 
  Kind getKind() const { return TheKind; }
  bool isDirect() const { return TheKind == Direct; }
  bool isIndirect() const { return TheKind == Indirect; }
  bool isIndirectAliased() const { return TheKind == IndirectAliased; }
  bool isIgnore() const { return TheKind == Ignore; }
  bool isExtend() const { return TheKind == Extend; }
  bool isCoerceAndExpand() const { return TheKind == CoerceAndExpand; }
 
  unsigned getDirectOffset() const {
    assert((isDirect() || isExtend()) && "Not a direct or extend kind");
    return DirectAttr.Offset;
  }
 
  /// How many integer and vector argument registers this argument occupies.
  /// Both zero means it occupies none and travels in memory, which is also
  /// what a target whose classifier does not record the demand reports.
  unsigned getNeededIntRegs() const { return NeededIntRegs; }
  unsigned getNeededSseRegs() const { return NeededSseRegs; }
 
  void setNeededRegs(unsigned IntRegs, unsigned SseRegs) {
    assert(IntRegs <= 7 && SseRegs <= 7 && "Register demand does not fit");
    NeededIntRegs = IntRegs;
    NeededSseRegs = SseRegs;
  }
 
  MaybeAlign getDirectAlign() const {
    assert((isDirect() || isExtend()) && "Not a direct or extend kind");
    return Alignment;
  }
 
  Align getIndirectAlign() const {
    assert((isIndirect() || isIndirectAliased()) && "Invalid Kind!");
    assert(Alignment.has_value() &&
           "Indirect arguments must have an alignment");
    return *Alignment;
  }
 
  unsigned getIndirectAddrSpace() const {
    assert((isIndirect() || isIndirectAliased()) && "Invalid Kind!");
    return IndirectAttr.AddrSpace;
  }
 
  bool getIndirectByVal() const {
    // Aliased pointers are never byval.
    assert(isIndirect() && "Invalid Kind!");
    return IndirectByVal;
  }
 
  bool getIndirectRealign() const {
    assert((isIndirect() || isIndirectAliased()) && "Invalid Kind!");
    return IndirectRealign;
  }
 
  /// Whether a Direct record coercion may be split into one wire argument
  /// per field. Mirrors clang::CodeGen::ABIArgInfo::CanBeFlattened.
  bool getCanBeFlattened() const {
    assert(isDirect() && "Invalid Kind!");
    return CanBeFlattened;
  }
 
  bool isSignExt() const {
    assert(isExtend() && "Invalid Kind!");
    return SignExt;
  }
 
  bool isZeroExt() const {
    assert(isExtend() && "Invalid Kind!");
    return ZeroExt;
  }
 
  bool isNoExt() const {
    assert(isExtend() && "Invalid Kind!");
    return !SignExt && !ZeroExt;
  }
 
  const Type *getCoerceToType() const {
    assert((isDirect() || isExtend() || isCoerceAndExpand()) &&
           "Invalid Kind!");
    return CoercionType;
  }
 
  const Type *getUnpaddedCoerceAndExpandType() const {
    assert(isCoerceAndExpand() && "Invalid Kind!");
    return UnpaddedCoerceAndExpandType;
  }
 
  /// True if \p Ty is an array of i8, the padding element of a
  /// coerce-and-expand type. A matrix is an array in this type system
  /// and lowers to a vector, so it is not padding.
  static bool isPaddingForCoerceAndExpand(const Type *Ty) {
    const auto *AT = dyn_cast<ArrayType>(Ty);
    if (!AT || AT->isMatrixType())
      return false;
    const auto *Elt = dyn_cast<IntegerType>(AT->getElementType());
    return Elt && Elt->getSizeInBits().getFixedValue() == 8;
  }
};
 
struct ArgEntry {
  const Type *ABIType;
  ArgInfo Info;
 
  ArgEntry(const Type *T) : ABIType(T), Info(ArgInfo::getDirect()) {}
  ArgEntry(const Type *T, ArgInfo A) : ABIType(T), Info(A) {}
};
 
/// Whether a signature accepts arguments beyond its declared parameters, and
/// where the declared ones end when it does.  An argument past an ellipsis is
/// unnamed, and some ABI rules pass an unnamed type differently.
///
/// A count and All are not interchangeable when the count equals the number of
/// arguments.  FunctionInfo::isVariadic() is true whenever a count was given,
/// so a signature with no ellipsis has to be spelled All.
class RequiredArgs {
  /// The number of leading arguments that are declared parameters, or ~0U if
  /// the signature accepts no optional arguments.
  unsigned NumRequired;
 
public:
  enum All_t { All };
 
  /// A signature with no ellipsis, where every argument is declared.
  RequiredArgs(All_t) : NumRequired(~0U) {}
 
  /// A signature whose leading \p N arguments are declared and whose remaining
  /// arguments pass through an ellipsis.
  explicit RequiredArgs(unsigned N) : NumRequired(N) {
    assert(N != ~0U && "~0U is reserved for a signature with no ellipsis");
  }
 
  bool allowsOptionalArgs() const { return NumRequired != ~0U; }
 
  unsigned getNumRequiredArgs() const {
    assert(allowsOptionalArgs() && "signature accepts no optional arguments");
    return NumRequired;
  }
};
 
class FunctionInfo final : private TrailingObjects<FunctionInfo, ArgEntry> {
private:
  const Type *ReturnType;
  ArgInfo ReturnInfo;
  unsigned NumArgs;
  CallingConv::ID CC = CallingConv::C;
  RequiredArgs Required;
 
  FunctionInfo(CallingConv::ID CC, const Type *RetTy, unsigned NumArguments,
               RequiredArgs Required)
      : ReturnType(RetTy), ReturnInfo(ArgInfo::getDirect()),
        NumArgs(NumArguments), CC(CC), Required(Required) {}
 
  friend class TrailingObjects;
 
public:
  using const_arg_iterator = const ArgEntry *;
  using arg_iterator = ArgEntry *;
 
  void operator delete(void *p) { ::operator delete(p); }
  const_arg_iterator arg_begin() const { return getTrailingObjects(); }
  const_arg_iterator arg_end() const { return getTrailingObjects() + NumArgs; }
  arg_iterator arg_begin() { return getTrailingObjects(); }
  arg_iterator arg_end() { return getTrailingObjects() + NumArgs; }
 
  unsigned arg_size() const { return NumArgs; }
 
  LLVM_ABI static std::unique_ptr<FunctionInfo>
  create(CallingConv::ID CC, const Type *ReturnType,
         ArrayRef<const Type *> ArgTypes,
         RequiredArgs Required = RequiredArgs::All);
 
  const Type *getReturnType() const { return ReturnType; }
  ArgInfo &getReturnInfo() { return ReturnInfo; }
  const ArgInfo &getReturnInfo() const { return ReturnInfo; }
 
  CallingConv::ID getCallingConvention() const { return CC; }
 
  bool isVariadic() const { return Required.allowsOptionalArgs(); }
 
  unsigned getNumRequiredArgs() const {
    return isVariadic() ? Required.getNumRequiredArgs() : arg_size();
  }
 
  ArrayRef<ArgEntry> arguments() const {
    return {getTrailingObjects(), NumArgs};
  }
 
  MutableArrayRef<ArgEntry> arguments() {
    return {getTrailingObjects(), NumArgs};
  }
 
  ArgEntry &getArgInfo(unsigned Index) {
    assert(Index < NumArgs && "Invalid argument index");
    return arguments()[Index];
  }
 
  const ArgEntry &getArgInfo(unsigned Index) const {
    assert(Index < NumArgs && "Invalid argument index");
    return arguments()[Index];
  }
};
 
} // namespace abi
} // namespace llvm
 
#endif // LLVM_ABI_FUNCTIONINFO_H