1//===- OffloadTargetVerifier.cpp ------------------------------------------===//
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// This pass verifies that values and symbols used within offload regions are
10// legal for the target execution model.
11//
12// Overview:
13// ---------
14// Offload regions execute on a target device (e.g., GPU) where not all values
15// and symbols from the host context are accessible. This pass checks that
16// live-in values (values defined outside but used inside the region) and
17// symbol references are valid for device execution.
18//
19// The pass operates on any operation implementing `OffloadRegionOpInterface`,
20// which includes OpenACC compute constructs (`acc.parallel`, `acc.kernels`,
21// `acc.serial`) as well as GPU operations like `gpu.launch`.
22//
23// Verification:
24// -------------
25// For each offload region, the pass checks:
26//
27// 1. Live-in Values: Values flowing into the region must be valid for device
28// use. This includes checking that data has been properly mapped via
29// OpenACC data clauses (copyin, copyout, present, etc.) or is a scalar
30// that can be passed by value.
31//
32// 2. Symbol References: Symbols referenced inside the region must be
33// accessible on the device. This includes checking for proper `declare`
34// attributes on globals or device-resident data attributes.
35//
36// Requirements:
37// -------------
38// 1. Target Region Identification: Operations representing offload regions
39// must implement `acc::OffloadRegionOpInterface`.
40//
41// 2. OpenACCSupport Analysis: The pass relies on the `OpenACCSupport`
42// analysis to determine value and symbol validity. This analysis provides
43// dialect-specific hooks for checking legality through `isValidValueUse`
44// and `isValidSymbolUse` methods. Custom dialect support can be registered
45// by providing a derived `OpenACCSupport` analysis before running this
46// pass.
47//
48// 3. Device Type: The `device_type` option specifies the target device.
49// For `host` or `multicore` targets, verification of ACC compute
50// constructs is not yet implemented.
51//
52//===----------------------------------------------------------------------===//
53
54#include "mlir/Analysis/Liveness.h"
55#include "mlir/Dialect/Func/IR/FuncOps.h"
56#include "mlir/Dialect/OpenACC/Analysis/OpenACCSupport.h"
57#include "mlir/Dialect/OpenACC/Extensions/AllExtensions.h"
58#include "mlir/Dialect/OpenACC/OpenACC.h"
59#include "mlir/Dialect/OpenACC/Transforms/Passes.h"
60#include "mlir/IR/SymbolTable.h"
61#include "llvm/Support/Debug.h"
62
63namespace mlir {
64namespace acc {
65#define GEN_PASS_DEF_OFFLOADTARGETVERIFIER
66#include "mlir/Dialect/OpenACC/Transforms/Passes.h.inc"
67} // namespace acc
68} // namespace mlir
69
70#define DEBUG_TYPE "offload-target-verifier"
71
72using namespace mlir;
73
74namespace {
75class OffloadTargetVerifier
76 : public acc::impl::OffloadTargetVerifierBase<OffloadTargetVerifier> {
77public:
78 using OffloadTargetVerifierBase::OffloadTargetVerifierBase;
79
80 void getDependentDialects(DialectRegistry &registry) const override {
81 OffloadTargetVerifierBase::getDependentDialects(registry);
82 acc::registerAllExtensions(registry);
83 }
84
85 /// Returns true if the target device type corresponds to host execution.
86 bool isHostTarget() const {
87 return deviceType == acc::DeviceType::Host ||
88 deviceType == acc::DeviceType::Multicore;
89 }
90
91 /// Check live-in values for legality.
92 SmallVector<Value>
93 getIllegalLiveInValues(Region &region, Liveness &liveness,
94 acc::OpenACCSupport &accSupport) const {
95 auto isInvalid = [&](Value val) -> bool {
96 return !accSupport.isValidValueUse(v: val, region);
97 };
98
99 SmallVector<Value> illegalValues(llvm::make_filter_range(
100 Range: liveness.getLiveIn(block: &region.front()), Pred: isInvalid));
101
102 return illegalValues;
103 }
104
105 /// Check symbol uses for legality.
106 SmallVector<SymbolTable::SymbolUse>
107 getIllegalUsedSymbols(Region &region, acc::OpenACCSupport &accSupport) const {
108 auto symUses = SymbolTable::getSymbolUses(from: &region);
109
110 // When there are no symbols used in the region, there are no illegal ones.
111 if (!symUses.has_value())
112 return {};
113
114 auto isInvalidSymbol = [&](const SymbolTable::SymbolUse &symUse) -> bool {
115 Operation *definingOp = nullptr;
116 return !accSupport.isValidSymbolUse(user: symUse.getUser(),
117 symbol: symUse.getSymbolRef(), definingOpPtr: &definingOp);
118 };
119
120 auto invalidSyms =
121 llvm::make_filter_range(Range&: symUses.value(), Pred: isInvalidSymbol);
122 SmallVector<SymbolTable::SymbolUse> invalidSymsList(invalidSyms);
123 return invalidSymsList;
124 }
125
126 /// Retrieve variable names for the given values.
127 static SmallVector<std::string>
128 getVariableNames(ArrayRef<Value> values, acc::OpenACCSupport &accSupport) {
129 SmallVector<std::string> names;
130 names.reserve(N: values.size());
131 for (Value value : values)
132 names.push_back(Elt: accSupport.getVariableName(v: value));
133 return names;
134 }
135
136 /// Check if the region has illegal live-in values.
137 bool hasIllegalLiveInValues(Operation *regionOp,
138 acc::OpenACCSupport &accSupport) const {
139 if (regionOp->getNumRegions() == 0)
140 return false;
141
142 Liveness liveness(regionOp);
143 SmallVector<Value> invalidValues =
144 getIllegalLiveInValues(region&: regionOp->getRegion(index: 0), liveness, accSupport);
145
146 bool hasIllegalValues = !invalidValues.empty();
147
148 if (hasIllegalValues) {
149 SmallVector<std::string> invalidVarNames =
150 getVariableNames(values: invalidValues, accSupport);
151
152 if (softCheck) {
153 // Emit warnings for each illegal value.
154 auto diag = regionOp->emitWarning(message: "offload target verifier: ")
155 << invalidValues.size() << " illegal live-in value(s)";
156 for (auto [invalidValue, name] :
157 llvm::zip(t&: invalidValues, u&: invalidVarNames)) {
158 if (name.empty()) {
159 diag.attachNote(noteLoc: invalidValue.getLoc()) << "value: " << invalidValue;
160 } else {
161 diag.attachNote(noteLoc: invalidValue.getLoc())
162 << "value: " << invalidValue << ", name: " << name;
163 }
164 }
165 } else {
166 std::string message = "offload target verifier failed due to " +
167 std::to_string(val: invalidValues.size()) +
168 " illegal live-in value(s)";
169 SmallVector<std::string> availableVarNames;
170 for (const std::string &name : invalidVarNames)
171 if (!name.empty())
172 availableVarNames.push_back(Elt: name);
173 if (!availableVarNames.empty())
174 message += " including: " + llvm::join(R&: availableVarNames, Separator: ", ");
175 accSupport.emitNYI(loc: regionOp->getLoc(), message);
176 }
177 }
178
179 return hasIllegalValues;
180 }
181
182 /// Check if the region has illegal symbol uses.
183 bool hasIllegalSymbolUses(Operation *regionOp,
184 acc::OpenACCSupport &accSupport) const {
185 if (regionOp->getNumRegions() == 0)
186 return false;
187
188 SmallVector<SymbolTable::SymbolUse> invalidSyms =
189 getIllegalUsedSymbols(region&: regionOp->getRegion(index: 0), accSupport);
190
191 bool hasIllegalSymbols = !invalidSyms.empty();
192
193 if (hasIllegalSymbols) {
194 auto getSymName = [&](SymbolTable::SymbolUse symUse) -> std::string {
195 return symUse.getSymbolRef().getLeafReference().str();
196 };
197 std::string invalidString =
198 llvm::join(R: llvm::map_range(C&: invalidSyms, F: getSymName), Separator: ", ");
199
200 // Emit only warnings when softCheck is enabled.
201 if (softCheck)
202 regionOp->emitWarning(message: "offload target verifier: illegal symbol(s): ")
203 << invalidString;
204 else
205 accSupport.emitNYI(loc: regionOp->getLoc(),
206 message: "offload target verifier failed due to illegal "
207 "symbol(s): " +
208 invalidString);
209 }
210
211 return hasIllegalSymbols;
212 }
213
214 void runOnOperation() override {
215 LLVM_DEBUG(llvm::dbgs() << "Enter OffloadTargetVerifier()\n");
216 func::FuncOp func = getOperation();
217
218 // Try to get cached parent analysis first, fall back to local analysis.
219 auto cachedAnalysis =
220 getCachedParentAnalysis<acc::OpenACCSupport>(parent: func->getParentOp());
221 acc::OpenACCSupport &accSupport = cachedAnalysis
222 ? cachedAnalysis->get()
223 : getAnalysis<acc::OpenACCSupport>();
224
225 bool hasErrors = false;
226
227 func.walk(callback: [&](Operation *op) {
228 // Only process offload region operations.
229 if (!isa<acc::OffloadRegionOpInterface>(Val: op))
230 return WalkResult::advance();
231
232 // TODO: Host/multicore verification for ACC compute constructs is not yet
233 // implemented.
234 if (isHostTarget() && isa<ACC_COMPUTE_CONSTRUCT_OPS>(Val: op)) {
235 accSupport.emitNYI(loc: op->getLoc(),
236 message: "host/multicore verification for ACC compute "
237 "constructs");
238 return WalkResult::advance();
239 }
240
241 // Check for illegal live-in values.
242 bool hasIllegalValues = hasIllegalLiveInValues(regionOp: op, accSupport);
243 if (hasIllegalValues)
244 hasErrors = true;
245
246 // Check for illegal symbol uses.
247 bool hasIllegalSyms = hasIllegalSymbolUses(regionOp: op, accSupport);
248 if (hasIllegalSyms)
249 hasErrors = true;
250
251 if (!hasIllegalValues && !hasIllegalSyms && softCheck)
252 op->emitRemark(message: "offload target verifier: passed validity check");
253
254 return WalkResult::advance();
255 });
256
257 if (hasErrors && !softCheck)
258 signalPassFailure();
259
260 LLVM_DEBUG(llvm::dbgs() << "Exit OffloadTargetVerifier()\n");
261 }
262};
263} // namespace
264