1 //===-- Lower/CustomIntrinsicCall.h -----------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 // Coding style: https://mlir.llvm.org/getting_started/DeveloperGuide/
10 //
11 //===----------------------------------------------------------------------===//
12 ///
13 /// Custom intrinsic lowering for the few intrinsic that have optional
14 /// arguments that prevents them to be handled in a more generic way in
15 /// IntrinsicCall.cpp.
16 /// The core principle is that this interface provides the intrinsic arguments
17 /// via callbacks to generate fir::ExtendedValue (instead of a list of
18 /// precomputed fir::ExtendedValue as done in the default intrinsic call
19 /// lowering). This gives more flexibility to only generate references to
20 /// dynamically optional arguments (pointers, allocatables, OPTIONAL dummies) in
21 /// a safe way.
22 //===----------------------------------------------------------------------===//
23 
24 #ifndef FORTRAN_LOWER_CUSTOMINTRINSICCALL_H
25 #define FORTRAN_LOWER_CUSTOMINTRINSICCALL_H
26 
27 #include "flang/Lower/AbstractConverter.h"
28 #include "llvm/ADT/Optional.h"
29 #include <functional>
30 
31 namespace Fortran {
32 
33 namespace evaluate {
34 class ProcedureRef;
35 struct SpecificIntrinsic;
36 } // namespace evaluate
37 
38 namespace lower {
39 
40 /// Does the call \p procRef to \p intrinsic need to be handle via this custom
41 /// framework due to optional arguments. Otherwise, the tools from
42 /// IntrinsicCall.cpp should be used directly.
43 bool intrinsicRequiresCustomOptionalHandling(
44     const Fortran::evaluate::ProcedureRef &procRef,
45     const Fortran::evaluate::SpecificIntrinsic &intrinsic,
46     AbstractConverter &converter);
47 
48 /// Type of callback to be provided to prepare the arguments fetching from an
49 /// actual argument expression.
50 using OperandPrepare = std::function<void(const Fortran::lower::SomeExpr &)>;
51 
52 /// Type of the callback to inquire about an argument presence, once the call
53 /// preparation was done. An absent optional means the argument is statically
54 /// present. An mlir::Value means the presence must be checked at runtime, and
55 /// that the value contains the "is present" boolean value.
56 using OperandPresent = std::function<llvm::Optional<mlir::Value>(std::size_t)>;
57 
58 /// Type of the callback to generate an argument reference after the call
59 /// preparation was done. For optional arguments, the utility guarantees
60 /// these callbacks will only be called in regions where the presence was
61 /// verified. This means the getter callback can dereference the argument
62 /// without any special care.
63 /// For elemental intrinsics, the getter must provide the current iteration
64 /// element value.
65 using OperandGetter = std::function<fir::ExtendedValue(std::size_t)>;
66 
67 /// Given a callback \p prepareOptionalArgument to prepare optional
68 /// arguments and a callback \p prepareOtherArgument to prepare non-optional
69 /// arguments prepare the intrinsic arguments calls.
70 /// It is up to the caller to decide what argument preparation means,
71 /// the only contract is that it should later allow the caller to provide
72 /// callbacks to generate argument reference given an argument index without
73 /// any further knowledge of the argument. The function simply visits
74 /// the actual arguments, deciding which ones are dynamically optional,
75 /// and calling the callbacks accordingly in argument order.
76 void prepareCustomIntrinsicArgument(
77     const Fortran::evaluate::ProcedureRef &procRef,
78     const Fortran::evaluate::SpecificIntrinsic &intrinsic,
79     llvm::Optional<mlir::Type> retTy,
80     const OperandPrepare &prepareOptionalArgument,
81     const OperandPrepare &prepareOtherArgument, AbstractConverter &converter);
82 
83 /// Given a callback \p getOperand to generate a reference to the i-th argument,
84 /// and a callback \p isPresentCheck to test if an argument is present, this
85 /// function lowers the intrinsic calls to \p name whose argument were
86 /// previously prepared with prepareCustomIntrinsicArgument. The elemental
87 /// aspects must be taken into account by the caller (i.e, the function should
88 /// be called during the loop nest generation for elemental intrinsics. It will
89 /// not generate any implicit loop nest on its own).
90 fir::ExtendedValue
91 lowerCustomIntrinsic(fir::FirOpBuilder &builder, mlir::Location loc,
92                      llvm::StringRef name, llvm::Optional<mlir::Type> retTy,
93                      const OperandPresent &isPresentCheck,
94                      const OperandGetter &getOperand, std::size_t numOperands,
95                      Fortran::lower::StatementContext &stmtCtx);
96 } // namespace lower
97 } // namespace Fortran
98 
99 #endif // FORTRAN_LOWER_CUSTOMINTRINSICCALL_H
100