openmp-utils.h

//===-- lib/Semantics/openmp-utils.h --------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
//
// Common utilities used in OpenMP semantic checks.
//
//===----------------------------------------------------------------------===//
 
#ifndef FORTRAN_SEMANTICS_OPENMP_UTILS_H
#define FORTRAN_SEMANTICS_OPENMP_UTILS_H
 
#include "flang/Evaluate/type.h"
#include "flang/Parser/char-block.h"
#include "flang/Parser/message.h"
#include "flang/Parser/openmp-utils.h"
#include "flang/Parser/parse-tree.h"
#include "flang/Parser/tools.h"
#include "flang/Semantics/tools.h"
 
#include "llvm/ADT/APInt.h"
#include "llvm/ADT/ArrayRef.h"
#include "llvm/ADT/DenseMap.h"
#include "llvm/ADT/SmallVector.h"
#include "llvm/Frontend/OpenMP/OMPContext.h"
#include "llvm/Frontend/OpenMP/OMPVersion.h"
 
#include <memory>
#include <optional>
#include <string>
#include <type_traits>
#include <utility>
#include <vector>
 
namespace Fortran::semantics {
class DeclTypeSpec;
class Scope;
class SemanticsContext;
class Symbol;
 
// Add this namespace to avoid potential conflicts
namespace omp {
using Fortran::parser::omp::BlockRange;
using Fortran::parser::omp::ExecutionPartIterator;
using Fortran::parser::omp::is_range_v;
using Fortran::parser::omp::LoopNestIterator;
using Fortran::parser::omp::LoopRange;
 
template <typename T, typename U = std::remove_const_t<T>> U AsRvalue(T &t) {
  return U(t);
}
 
template <typename T> T &&AsRvalue(T &&t) { return std::move(t); }
 
struct SemanticOverrides {
  // Map of clauses and which directives they are considered to be allowed on
  // for the purpose of this compilation despite not being allowed by strict
  // interpretation of the selected spec version.
  // This is to record cases where we allow a clause because a past/future
  // spec allows it. This is needed for consistent treatment of clauses as
  // allowed/disallowed.
  llvm::DenseMap<llvm::omp::Clause, llvm::omp::Directives> allowedClauses;
};
 
bool IsClauseAllowedOnDirective(llvm::omp::Clause clauseId,
    llvm::omp::Directive dirId, llvm::omp::Version ver,
    SemanticOverrides *overrides);
 
bool IsClauseAllowedOnDirective(llvm::omp::Clause clauseId,
    llvm::omp::Directive dirId, llvm::omp::Version version,
    SemanticsContext *semaCtx);
 
const Scope &GetScopingUnit(const Scope &scope);
const Scope &GetProgramUnit(const Scope &scope);
 
// There is no consistent way to get the source of an ActionStmt, but there
// is "source" in Statement<T>. This structure keeps the ActionStmt with the
// extracted source for further use.
struct SourcedActionStmt
    : public parser::omp::WithSource<const parser::ActionStmt *> {
  using parser::omp::WithSource<value_type>::WithSource;
  value_type stmt() const { return value; }
  operator bool() const { return stmt() != nullptr; }
};
 
SourcedActionStmt GetActionStmt(const parser::ExecutionPartConstruct *x);
SourcedActionStmt GetActionStmt(const parser::Block &block);
 
std::string ThisVersion(llvm::omp::Version version);
std::string TryVersion(llvm::omp::Version version);
 
const Symbol *GetObjectSymbol(
    const parser::OmpObject &object, bool ultimate = false);
const Symbol *GetArgumentSymbol(
    const parser::OmpArgument &argument, bool ultimate = false);
 
bool IsCommonBlock(const Symbol &sym);
bool IsExtendedListItem(const Symbol &sym);
bool IsVariableListItem(const Symbol &sym);
bool IsTypeParamInquiry(const Symbol &sym);
bool IsComplexPart(const Symbol &sym);
bool IsStructureComponent(const Symbol &sym);
bool IsPrivatizable(const Symbol &sym);
bool IsVarOrFunctionRef(const MaybeExpr &expr);
 
bool IsWholeAssumedSizeArray(const parser::OmpObject &object);
 
bool IsExtendedListItem(
    const parser::OmpObject &object, SemanticsContext *semaCtx);
bool IsLocatorListItem(
    const parser::OmpObject &object, SemanticsContext *semaCtx);
bool IsVariableListItem(
    const parser::OmpObject &object, SemanticsContext *semaCtx);
 
// Analyzes potential substrings and retains diagnostics; may modify semantic
// state and the parse tree. A missing result indicates an invalid designator,
// already diagnosed.
std::optional<bool> IsSubstringAndValidate(
    const parser::OmpObject &object, SemanticsContext *semaCtx);
bool IsArrayElement(const parser::OmpObject &object, SemanticsContext *semaCtx);
 
const Symbol *GetHostSymbol(const Symbol &sym);
 
// Resolve a user-defined reduction visible in scope under the mangled name
// mangledName (e.g. "op.myop." for operator(.myop.), or a named reduction).
// Follows USE associations, operator renames, private visibility, and merged
// generics exactly as the OpenMP semantic checks do, returning the found
// (non-ultimate) reduction symbol, or null if none is visible. When type is
// non-null, only a reduction that supports that type is accepted (used to
// disambiguate an operator that carries reductions for several types). When
// ambiguous is non-null, it is set true if more than one distinct reduction
// supports the type (an operator merged from several modules that each declare
// a reduction for it, or a mangled reduction name that collides across
// modules).
const Symbol *FindUserReductionSymbol(const Scope &scope,
    const parser::CharBlock &mangledName, const DeclTypeSpec *type = nullptr,
    bool *ambiguous = nullptr);
 
// Resolve the user-defined reduction associated with the defined-operator
// symbol operatorSym. Delegates to FindUserReductionSymbol from scope (the
// scope where the reduction clause appears) with the operator's mangled
// ("op...") name. Searching from the clause scope, not the operator's owning
// scope, finds a reduction that is local, host-, or use-associated there (a
// reduction may be declared in a contained procedure that host-associates the
// operator from an enclosing module). type filters by supported type as above.
const Symbol *FindOperatorUserReductionSymbol(const Scope &scope,
    const Symbol &operatorSym, const DeclTypeSpec *type = nullptr);
 
bool IsMapEnteringType(parser::OmpMapType::Value type);
bool IsMapExitingType(parser::OmpMapType::Value type);
 
// Returns true if the symbol has a temporary stack-allocated descriptor.
// This includes assumed-shape and assumed-rank dummy arguments that are
// not allocatable or pointer. These descriptors are created on the caller's
// stack and become invalid after the function returns.
bool HasTemporaryStackDescriptor(const Symbol &symbol);
 
MaybeExpr GetEvaluateExpr(const parser::Expr &parserExpr);
template <typename T> MaybeExpr GetEvaluateExpr(const T &inp) {
  return GetEvaluateExpr(parser::UnwrapRef<parser::Expr>(inp));
}
 
std::optional<evaluate::DynamicType> GetDynamicType(
    const parser::Expr &parserExpr);
 
std::optional<bool> GetLogicalValue(const SomeExpr &expr);
std::optional<int64_t> GetIntValueFromExpr(
    const parser::Expr &parserExpr, SemanticsContext *semaCtx = nullptr);
 
template <typename T>
std::optional<int64_t> GetIntValueFromExpr(
    const T &wrappedExpr, SemanticsContext *semaCtx = nullptr) {
  if (auto *parserExpr{parser::Unwrap<parser::Expr>(wrappedExpr)}) {
    return GetIntValueFromExpr(*parserExpr, semaCtx);
  }
  return std::nullopt;
}
 
// There are several clauses that take an optional, compile-time
// constant bool argument. Those clauses are stored as std::optional, e.g.
// OmpClause::ReverseOffload -> std::optional<OmpReverseOffloadClause>.
// Retrieve the logical value if present.
template <typename ClauseTy>
std::optional<bool> GetLogicalArgument(
    const std::optional<ClauseTy> &maybeClause, SemanticsContext &semaCtx) {
  if (maybeClause) {
    // Scalar<Logical<Constant<common::Indirection<Expr>>>>
    auto &parserExpr{parser::UnwrapRef<parser::Expr>(*maybeClause)};
    evaluate::ExpressionAnalyzer ea{semaCtx};
    if (auto &&maybeExpr{ea.Analyze(parserExpr)}) {
      if (auto v{GetLogicalValue(*maybeExpr)}) {
        return *v;
      }
    }
  }
  return std::nullopt;
}
 
std::optional<bool> IsContiguous(
    SemanticsContext &semaCtx, const parser::OmpObject &object);

struct DynamicUserCondition {
  const parser::ScalarExpr *expr;
  parser::CharBlock source;
};

enum class UnsupportedSelectorFeature {
  None,
  TargetDevice,
  ClauseOrExtensionProperty,
};

UnsupportedSelectorFeature FindUnsupportedSelectorFeature(
    const parser::traits::OmpContextSelectorSpecification &ctxSel,
    SemanticsContext &semaCtx);

std::optional<DynamicUserCondition> MakeVariantMatchInfo(
    llvm::omp::VariantMatchInfo &vmi,
    const parser::traits::OmpContextSelectorSpecification &ctxSel,
    SemanticsContext &semaCtx);

class OmpVariantMatchContext : public llvm::omp::OMPContext {
public:
  OmpVariantMatchContext(bool isDeviceCompilation, llvm::Triple targetTriple,
      llvm::Triple targetOffloadTriple, std::string targetFeatures,
      llvm::ArrayRef<llvm::omp::TraitProperty> constructTraits = {});
  OmpVariantMatchContext(const SemanticsContext &context,
      llvm::ArrayRef<llvm::omp::TraitProperty> constructTraits = {});
  bool matchesISATrait(llvm::StringRef rawString) const override;
 
private:
  std::string features_;
};
 
struct MetadirectiveCandidate {
  MetadirectiveCandidate(const parser::OmpDirectiveSpecification *spec,
      llvm::omp::VariantMatchInfo vmi, bool isExplicit,
      std::optional<DynamicUserCondition> dynamicCondition = std::nullopt,
      bool conditionShouldBeTrue = true)
      : spec{spec}, vmi{std::move(vmi)}, isExplicit{isExplicit},
        dynamicCondition{dynamicCondition},
        conditionShouldBeTrue{conditionShouldBeTrue} {}
 
  const parser::OmpDirectiveSpecification *spec{nullptr};
  llvm::omp::VariantMatchInfo vmi;
  bool isExplicit{false};
  std::optional<DynamicUserCondition> dynamicCondition;
  bool conditionShouldBeTrue{true};
};
 
struct MetadirectiveCandidateSet {
  llvm::SmallVector<MetadirectiveCandidate, 4> candidates;
  const parser::OmpDirectiveSpecification *fallback{nullptr};
};
 
const parser::OmpContextSelector *GetContextSelector(
    const parser::OmpClause &clause);
const parser::OmpDirectiveSpecification *GetDirectiveVariant(
    const parser::OmpClause &clause);

std::optional<MetadirectiveCandidateSet> BuildMetadirectiveCandidateSet(
    const parser::OmpClauseList &clauses, SemanticsContext &context,
    const OmpVariantMatchContext &matchContext);
 
std::optional<unsigned> SelectBestMetadirectiveCandidate(
    llvm::ArrayRef<unsigned> candidateIndices,
    llvm::ArrayRef<MetadirectiveCandidate> candidates,
    const OmpVariantMatchContext &matchContext);

bool IsRepeatableMetadirectiveCondition(
    const parser::ScalarExpr &condition, SemanticsContext &context);

bool AreSameRepeatableMetadirectiveCondition(const parser::ScalarExpr &left,
    const parser::ScalarExpr &right, SemanticsContext &context);

llvm::SmallVector<unsigned, 4> GetMetadirectiveElsePathCandidates(
    unsigned selectedIndex, llvm::ArrayRef<unsigned> candidateIndices,
    llvm::ArrayRef<MetadirectiveCandidate> candidates,
    const OmpVariantMatchContext &matchContext, SemanticsContext &context);

llvm::SmallVector<const parser::OmpDirectiveSpecification *, 4>
GetReachableMetadirectiveVariants(const MetadirectiveCandidateSet &candidateSet,
    const OmpVariantMatchContext &matchContext, SemanticsContext &context);

bool MayVariantBeSelected(
    const parser::traits::OmpContextSelectorSpecification *selector,
    SemanticsContext &context, OmpVariantMatchContext &matchContext);
 
std::vector<SomeExpr> GetTopLevelDesignators(const SomeExpr &expr);
const SomeExpr *HasStorageOverlap(
    const SomeExpr &base, llvm::ArrayRef<SomeExpr> exprs);
 
bool IsAssignment(const parser::ActionStmt *x);
bool IsPointerAssignment(const evaluate::Assignment &x);
 
MaybeExpr MakeEvaluateExpr(const parser::OmpStylizedInstance &inp);
 
enum struct ListItemKind : uint32_t {
  Depend,
  DirectiveName,
  DirectiveSpecification,
  Extended,
  IntegerExpression,
  Interop,
  Locator,
  Operation,
  Parameter,
  ProcedureArgument,
  Variable,
};
 
std::optional<ListItemKind> GetArgumentListItemKind(
    llvm::omp::Clause clause, llvm::omp::Version version);
 
bool IsLoopTransforming(llvm::omp::Directive dir);
bool HasDataEnvironment(llvm::omp::Directive dir);
 
bool IsFullUnroll(const parser::OmpDirectiveSpecification &spec);

struct OmpErrorArgs {
  parser::OmpAtClause::ActionTime at{
      parser::OmpAtClause::ActionTime::Compilation};
  parser::OmpSeverityClause::SevLevel severity{
      parser::OmpSeverityClause::SevLevel::Fatal};
  const parser::Expr *message{nullptr};
};

OmpErrorArgs GetErrorDirectiveArgs(
    const parser::OmpDirectiveSpecification &spec);
OmpErrorArgs GetErrorDirectiveArgs(const parser::OmpErrorDirective &errDir);
 
inline bool IsDoConcurrentLegal(llvm::omp::Version version) {
  // DO CONCURRENT is allowed (as an alternative to a Canonical Loop Nest)
  // in OpenMP 6.0+.
  return version >= 60;
}
 
struct LoopControl {
  LoopControl(LoopControl &&x) = default;
  LoopControl(const LoopControl &x) = default;
  LoopControl(const parser::LoopControl::Bounds &x);
  LoopControl(const parser::ConcurrentControl &x);
 
  const parser::Name &iv;
  parser::omp::WithSource<MaybeExpr> lbound, ubound, step;
 
private:
  static parser::omp::WithSource<MaybeExpr> fromParserExpr(
      const parser::Expr &x);
};
 
std::vector<LoopControl> GetLoopControls(const parser::DoConstruct &x);

struct Reason {
  Reason() = default;
  Reason(Reason &&) = default;
  Reason(const Reason &);
  Reason &operator=(Reason &&) = default;
  Reason &operator=(const Reason &);
 
  parser::Messages msgs;
 
  template <typename... Ts> Reason &Say(Ts &&...args) {
    msgs.Say(std::forward<Ts>(args)...);
    return *this;
  }
  parser::Message &AttachTo(parser::Message &msg);
  Reason &Append(const Reason &other) {
    CopyFrom(other);
    return *this;
  }
  operator bool() const { return !msgs.empty(); }
 
private:
  void CopyFrom(const Reason &other);
};
 
// A property with an explanation of its value. Both, the property and the
// reason are optional (the reason can have no messages in it).
template <typename T> struct WithReason {
  std::optional<T> value;
  Reason reason;
 
  WithReason() = default;
  WithReason(std::optional<T> v, const Reason &r = Reason())
      : value(v), reason(r) {}
  operator bool() const { return value.has_value(); }
};
 
WithReason<int64_t> GetArgumentValueWithReason(
    const parser::OmpDirectiveSpecification &spec, llvm::omp::Clause clauseId,
    llvm::omp::Version version, SemanticsContext *semaCtx = nullptr);
WithReason<int64_t> GetNumArgumentsWithReason(
    const parser::OmpDirectiveSpecification &spec, llvm::omp::Clause clauseId,
    llvm::omp::Version version, SemanticsContext *semaCtx = nullptr);
WithReason<int64_t> GetHeightWithReason(
    const parser::OmpDirectiveSpecification &spec, llvm::omp::Version version,
    SemanticsContext *semaCtx = nullptr);

std::pair<WithReason<int64_t>, bool> GetAffectedNestDepthWithReason(
    const parser::OmpDirectiveSpecification &spec, llvm::omp::Version version,
    SemanticsContext *semaCtx = nullptr);
std::pair<WithReason<int64_t>, bool> GetGeneratedNestDepthWithReason(
    const parser::OmpDirectiveSpecification &spec, llvm::omp::Version version,
    SemanticsContext *semaCtx = nullptr);
WithReason<std::pair<int64_t, int64_t>> GetAffectedLoopRangeWithReason(
    const parser::OmpDirectiveSpecification &spec, llvm::omp::Version version,
    SemanticsContext *semaCtx = nullptr);
WithReason<int64_t> GetRectangularNestDepthWithReason(
    const parser::OmpDirectiveSpecification &spec, llvm::omp::Version version,
    SemanticsContext *semaCtx = nullptr);

std::optional<int64_t> GetMinimumSequenceCount(
    std::optional<int64_t> first, std::optional<int64_t> count);
std::optional<int64_t> GetMinimumSequenceCount(
    std::optional<std::pair<int64_t, int64_t>> range);

std::optional<std::vector<const parser::DoConstruct *>> CollectAffectedDoLoops(
    const parser::OpenMPLoopConstruct &x, llvm::omp::Version version,
    SemanticsContext *semaCtx = nullptr);

bool IsDoacrossAffected(const parser::OpenMPLoopConstruct &x);
 
struct LoopSequence {
  LoopSequence(const parser::ExecutionPartConstruct &root,
      llvm::omp::Version version, bool allowAllLoops = false,
      SemanticsContext *semaCtx = nullptr);
 
  template <typename R, typename = std::enable_if_t<is_range_v<R>>>
  LoopSequence(const R &range, llvm::omp::Version version,
      bool allowAllLoops = false, SemanticsContext *semaCtx = nullptr)
      : version_(version), allowAllLoops_(allowAllLoops), semaCtx_(semaCtx) {
    entry_ = std::make_unique<Construct>(range, nullptr);
    createChildrenFromRange(entry_->location);
    precalculate();
  }
 
  struct Depth {
    // If this sequence is a nest, the depth of the Canonical Loop Nest rooted
    // at this sequence. Otherwise unspecified.
    WithReason<int64_t> semantic;
    // If this sequence is a nest, the depth of the perfect Canonical Loop Nest
    // rooted at this sequence. Otherwise unspecified.
    WithReason<int64_t> perfect;
  };
 
  bool isNest() const { return length_.value == 1; }
  const WithReason<int64_t> &length() const { return length_; }
  const WithReason<int64_t> &height() const { return height_; }
  const Depth &depth() const { return depth_; }
  const std::vector<LoopSequence> &children() const { return children_; }
  const parser::ExecutionPartConstruct *owner() const { return entry_->owner; }
 
  WithReason<bool> isWellFormedSequence() const;
  WithReason<bool> isWellFormedNest() const;

  const LoopSequence *getNestedDoConcurrent() const;
 
  std::vector<LoopControl> getLoopControls() const;
  // Check if this loop's bounds are invariant in each of the `outer`
  // constructs.
  WithReason<bool> isRectangular(
      const std::vector<const LoopSequence *> &outer) const;
 
private:
  using Construct = ExecutionPartIterator::Construct;
 
  LoopSequence(std::unique_ptr<Construct> entry, llvm::omp::Version version,
      bool allowAllLoops, SemanticsContext *semaCtx = nullptr);
 
  template <typename R, typename = std::enable_if_t<is_range_v<R>>>
  void createChildrenFromRange(const R &range) {
    createChildrenFromRange(range.begin(), range.end());
  }
 
  std::unique_ptr<Construct> createConstructEntry(
      const parser::ExecutionPartConstruct &code);
 
  void createChildrenFromRange( //
      ExecutionPartIterator::IteratorType begin,
      ExecutionPartIterator::IteratorType end);

  void precalculate();
 
  WithReason<int64_t> calculateLength() const;
  WithReason<int64_t> getNestedLength() const;
  Depth calculateDepths() const;
  Depth getNestedDepths() const;
  WithReason<int64_t> calculateHeight() const;

  const parser::ExecutionPartConstruct *invalidIC_{nullptr};
  const parser::ExecutionPartConstruct *opaqueIC_{nullptr};

  WithReason<int64_t> length_;
  Depth depth_;
  WithReason<int64_t> height_;
 
  // The core structure of the class:
  llvm::omp::Version version_; // Needed for GetXyzWithReason
  bool allowAllLoops_;
  std::unique_ptr<Construct> entry_;
  std::vector<LoopSequence> children_;
  SemanticsContext *semaCtx_{nullptr};
};
 
// ---------------------------------------------------------------------------
// Trait-matching helpers shared between metadirective lowering and
// declare-variant semantic recording.
// ---------------------------------------------------------------------------

llvm::omp::TraitSet MapTraitSet(parser::OmpTraitSetSelectorName::Value name);

llvm::omp::TraitSelector MapTraitSelector(
    const parser::OmpTraitSelectorName &name, llvm::omp::TraitSet set);

std::optional<bool> EvaluateUserCondition(
    SemanticsContext &semaCtx, const parser::ScalarExpr &scalarExpr);

llvm::APInt *GetTraitScore(
    const std::optional<parser::OmpTraitSelector::Properties> &props,
    SemanticsContext &semaCtx, std::optional<llvm::APInt> &scoreStorage);

void ProcessTraitProperties(llvm::omp::VariantMatchInfo &vmi,
    llvm::omp::TraitSet set, llvm::omp::TraitSelector selector,
    const std::optional<parser::OmpTraitSelector::Properties> &props,
    llvm::APInt *scorePtr);
 
} // namespace omp
} // namespace Fortran::semantics
 
#endif // FORTRAN_SEMANTICS_OPENMP_UTILS_H