MLIR-AIE 1.4.6.dev
AIECertVerify.cpp
Go to the documentation of this file.
1//===- AIECertVerify.cpp ---------------------------------------*- C++ -*-===//
2//
3// Copyright (C) 2026 Advanced Micro Devices, Inc.
4// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
5//
6//===----------------------------------------------------------------------===//
7
11
12#include "mlir/Pass/Pass.h"
13
14#include "llvm/ADT/STLExtras.h"
15#include "llvm/ADT/SmallVector.h"
16#include "llvm/ADT/StringRef.h"
17
18#include <algorithm>
19#include <map>
20#include <set>
21#include <tuple>
22#include <utility>
23
24namespace xilinx::AIEX {
25#define GEN_PASS_DEF_AIECERTVERIFY
26#include "aie/Dialect/AIEX/Transforms/AIEXPasses.h.inc"
27} // namespace xilinx::AIEX
28
29using namespace mlir;
30using namespace xilinx;
31
32#define DEBUG_TYPE "cert-verify"
33
34namespace {
35
36// The firmware indexes job contexts by job_id % 64 and reuses them on the next
37// page, so job IDs on one page must differ modulo 64.
38static LogicalResult checkJobSlots(AIE::DeviceOp device) {
39 LogicalResult result = success();
40 device.walk([&](AIEX::CertPageOp page) {
41 llvm::DenseMap<unsigned, AIEX::CertJobOp> slots;
42 for (auto job : page.getBody().front().getOps<AIEX::CertJobOp>()) {
43 unsigned slot = job.getJobId() % AIEX::CertJobOp::NumSlots;
44 auto [it, inserted] = slots.try_emplace(slot, job);
45 if (!inserted) {
46 job.emitError() << "job ID " << job.getJobId()
47 << " collides with job ID " << it->second.getJobId()
48 << " modulo " << AIEX::CertJobOp::NumSlots
49 << " on the same page";
50 result = failure();
51 }
52 }
53 });
54 return result;
55}
56
57// The uC (CERT group) id of a cert op is the group_id of its nearest enclosing
58// cert.attach_to_group, or 0 if it is at device level.
59static int getUcGroupId(Operation *op) {
60 auto group = op->getParentOfType<AIEX::CertAttachToGroupOp>();
61 return group ? group.getGroupID() : 0;
62}
63
64// G-localbar: within each uC scope, all cert.local_barrier ops that share a
65// local_barrier_id must reside in the same cert.page (their participants must
66// be co-resident on one page, else the firmware hangs).
67static LogicalResult checkLocalBarrierColocation(AIE::DeviceOp device) {
68 LogicalResult result = success();
69 // Before page formation, a standalone job is its own co-location scope.
70 std::map<std::pair<int, int>, Operation *> firstScope;
71 device.walk(
72 [&](AIEX::CertLocalBarrierOp barrier) {
73 int uc = getUcGroupId(barrier);
74 int id = static_cast<int>(barrier.getLocalBarrierId());
75 Operation *scope = barrier->getParentOfType<AIEX::CertPageOp>();
76 if (!scope)
77 scope = barrier->getParentOfType<AIEX::CertJobOp>();
78 auto key = std::make_pair(uc, id);
79 auto it = firstScope.find(key);
80 if (it == firstScope.end()) {
81 firstScope[key] = scope;
82 return;
83 }
84 if (it->second != scope) {
85 barrier.emitError()
86 << "cert.local_barrier "
87 << stringifyCertLocalBarrierId(barrier.getLocalBarrierId())
88 << " in uC " << uc
89 << " must be on the same page as its other participants";
90 result = failure();
91 }
92 });
93 return result;
94}
95
96// Firmware keeps one outstanding TCT count per actor. Concurrent jobs waiting
97// on the same (tile, channel) would over-wait; sequential waits within a job or
98// on different pages are safe. Bare jobs use their own scope until
99// legalization.
100static LogicalResult checkWaitTctsUniqueness(AIE::DeviceOp device) {
101 LogicalResult result = success();
102 // (page scope, tile, channel) -> the job that already waits on that actor.
103 std::map<std::tuple<Operation *, int, int>, Operation *> seen;
104 device.walk([&](AIEX::CertWaitTCTSOp wait) {
105 int tile = wait.getTileId();
106 int channel = wait.getChannelId();
107 Operation *job = wait->getParentOfType<AIEX::CertJobOp>();
108 Operation *scope = wait->getParentOfType<AIEX::CertPageOp>();
109 if (!scope)
110 scope = job;
111 auto key = std::make_tuple(scope, tile, channel);
112 auto it = seen.find(key);
113 if (it == seen.end()) {
114 seen[key] = job;
115 return;
116 }
117 // Same job: sequential within one thread of control, so legal.
118 if (it->second == job)
119 return;
120 wait.emitError() << "more than one job on this cert.page waits on tile "
121 << tile << " channel " << channel << " in uC "
122 << getUcGroupId(wait)
123 << "; at most one job per page may wait_tcts on a given "
124 "(tile, channel)";
125 result = failure();
126 });
127 return result;
128}
129
130static std::set<int> computePresentUcs(AIE::DeviceOp device) {
131 std::set<int> present;
132 device.walk([&](AIEX::CertAttachToGroupOp group) {
133 present.insert(group.getGroupID());
134 });
135 if (!device.getBody()->getOps<AIEX::CertPageOp>().empty() ||
136 !device.getBody()->getOps<AIEX::CertJobOp>().empty() ||
137 !device.getBody()->getOps<AIEX::CertSectionOp>().empty())
138 present.insert(0);
139 return present;
140}
141
142// Firmware requires each controller to expose the same preemption IDs,
143// including multiplicity. Compare against the lowest present controller ID.
144static LogicalResult checkPreemptConsistency(AIE::DeviceOp device) {
145 std::map<int, std::multiset<int>> preemptIds;
146 std::map<int, AIEX::CertAttachToGroupOp> repAttach;
147 std::set<int> present;
148
149 // Every attach_to_group establishes a present uC.
150 device.walk([&](AIEX::CertAttachToGroupOp group) {
151 int uc = group.getGroupID();
152 present.insert(uc);
153 if (!repAttach.count(uc))
154 repAttach[uc] = group;
155 });
156
157 // Device-level cert content lives on uC 0.
158 if (!device.getBody()->getOps<AIEX::CertPageOp>().empty() ||
159 !device.getBody()->getOps<AIEX::CertJobOp>().empty() ||
160 !device.getBody()->getOps<AIEX::CertSectionOp>().empty())
161 present.insert(0);
162
163 // Collect the preempt ids per uC.
164 device.walk([&](AIEX::CertPreemptOp preempt) {
165 int uc = getUcGroupId(preempt);
166 present.insert(uc);
167 preemptIds[uc].insert(preempt.getId());
168 });
169
170 if (present.size() < 2)
171 return success();
172
173 int ref = *present.begin();
174 const std::multiset<int> &refSet = preemptIds[ref];
175 LogicalResult result = success();
176 for (int uc : present) {
177 if (uc == ref)
178 continue;
179 if (preemptIds[uc] != refSet) {
180 Operation *loc = repAttach.count(uc) ? repAttach[uc].getOperation()
181 : device.getOperation();
182 loc->emitError()
183 << "cert.preempt ids on uC " << uc << " differ from uC " << ref
184 << "; all uCs must have the same preempt ids (G-preempt)";
185 result = failure();
186 }
187 }
188 return result;
189}
190
191// Group/placement ids must be valid microcontroller indices for the device:
192// nonnegative, less than the number of uCs, and (defensively) < 32 so they are
193// representable in a party mask. Rejecting invalid ids up front keeps later
194// checks (e.g. the remote-barrier mask shift) free of undefined behavior.
195static LogicalResult checkGroupIds(AIE::DeviceOp device) {
196 const AIE::AIETargetModel &tm = device.getTargetModel();
197 int64_t numUcs = std::min<int64_t>(tm.getNumControllers(), 32);
198 LogicalResult result = success();
199 auto checkId = [&](Operation *op, int64_t id, llvm::StringRef what) {
200 if (id < 0 || id >= numUcs) {
201 op->emitError() << what << " " << id << " is not a valid uC id [0, "
202 << numUcs << ")";
203 result = failure();
204 }
205 };
206 device.walk([&](AIEX::CertAttachToGroupOp g) {
207 checkId(g, g.getGroupID(), "cert.attach_to_group group id");
208 });
209 // The verifier may run before placement lowering; check any leftover attrs.
210 device.walk([&](AIEX::CertPageOp p) {
211 if (auto pl = p.getPlacementAttr())
212 checkId(p, pl.getInt(), "cert.page placement");
213 });
214 return result;
215}
216
217// G-uC / rendezvous: cross-uC remote barriers must actually rendezvous. Group
218// occurrences by remote_barrier_id and require: all occurrences agree on
219// party_mask; every mask bit names a present uC that has a matching occurrence
220// (so nobody waits forever); each participating uC sets its own bit; and at
221// most one occurrence per uC per id (one participant per column). Assumes group
222// ids are already validated by checkGroupIds (shifts are still guarded).
223static LogicalResult checkRemoteBarrierParties(AIE::DeviceOp device) {
224 std::set<int> present = computePresentUcs(device);
225 LogicalResult result = success();
226
227 std::map<AIEX::CertRemoteBarrierId, SmallVector<AIEX::CertRemoteBarrierOp, 4>>
228 byId;
229 device.walk([&](AIEX::CertRemoteBarrierOp b) {
230 byId[b.getRemoteBarrierId()].push_back(b);
231 });
232
233 for (auto &entry : byId) {
234 StringRef id = stringifyCertRemoteBarrierId(entry.first);
235 SmallVector<AIEX::CertRemoteBarrierOp, 4> &occs = entry.second;
236
237 // All occurrences of an id must describe the same rendezvous.
238 uint32_t mask = occs.front().getPartyMask();
239 bool masksAgree = llvm::all_of(occs, [&](AIEX::CertRemoteBarrierOp b) {
240 return b.getPartyMask() == mask;
241 });
242 if (!masksAgree) {
243 for (auto b : occs)
244 b.emitError() << "cert.remote_barrier " << id
245 << " occurrences disagree on party_mask";
246 result = failure();
247 continue;
248 }
249
250 // Participating uCs (from occurrences); own-bit + one-per-uC checks.
251 std::map<int, int> occPerUc;
252 for (auto b : occs) {
253 int own = getUcGroupId(b);
254 occPerUc[own]++;
255 if (own >= 0 && own < 32 && !((mask >> own) & 1u)) {
256 b.emitError() << "cert.remote_barrier " << id << " on uC " << own
257 << " excludes its own uC from party_mask";
258 result = failure();
259 }
260 }
261 for (auto &[uc, count] : occPerUc)
262 if (count > 1) {
263 occs.front().emitError()
264 << "cert.remote_barrier " << id << " has " << count
265 << " occurrences on uC " << uc
266 << " (at most one participant per uC per rendezvous)";
267 result = failure();
268 }
269
270 // Every mask bit must be a present uC that has a matching barrier.
271 for (int bit = 0; bit < 32; ++bit) {
272 if (!((mask >> bit) & 1u))
273 continue;
274 if (!present.count(bit)) {
275 occs.front().emitError()
276 << "cert.remote_barrier " << id << " party_mask references uC "
277 << bit << " which is not present in the design";
278 result = failure();
279 } else if (!occPerUc.count(bit)) {
280 occs.front().emitError()
281 << "cert.remote_barrier " << id << " party_mask includes uC " << bit
282 << " but that uC has no matching remote_barrier(" << id
283 << ") to rendezvous with";
284 result = failure();
285 }
286 }
287 }
288 return result;
289}
290
291// The register `op` writes, if any. cert.write32_d only reads registers.
292static std::optional<uint32_t> registerWrittenBy(Operation &op) {
293 if (auto o = dyn_cast<AIEX::CertUcDmaWriteDesOp>(op))
294 return o.getWaitHandle();
295 if (auto o = dyn_cast<AIEX::CertRead32Op>(op))
296 return o.getValue();
297 if (auto o = dyn_cast<AIEX::CertRead32DOp>(op))
298 return o.getValue();
299 return std::nullopt;
300}
301
302// A cert.wait_uc_dma handle must be a local register r0..r7 whose last write
303// earlier in the same job is a cert.uc_dma_write_des. A read into that register
304// in between replaces the handle.
305static LogicalResult checkUcDmaWaitHandles(AIE::DeviceOp device) {
306 LogicalResult result = success();
307 device.walk([&](AIEX::CertJobOp job) {
308 llvm::SmallDenseMap<uint32_t, Operation *> lastWrite;
309 for (Operation &o : job.getBody().front()) {
310 if (auto wait = dyn_cast<AIEX::CertWaitUcDmaOp>(o)) {
311 uint32_t r = wait.getWaitHandle();
312 auto it = lastWrite.find(r);
313 if (r >= 8) {
314 wait.emitError() << "cert.wait_uc_dma handle r" << r
315 << " is a shared register; the handle must be a "
316 "local register r0..r7 written by a "
317 "cert.uc_dma_write_des in the same job";
318 result = failure();
319 } else if (it == lastWrite.end()) {
320 wait.emitError() << "cert.wait_uc_dma waits on r" << r
321 << ", which no earlier cert.uc_dma_write_des in "
322 "this job writes";
323 result = failure();
324 } else if (!isa<AIEX::CertUcDmaWriteDesOp>(it->second)) {
325 wait.emitError() << "cert.wait_uc_dma waits on r" << r
326 << ", but its last write is a '"
327 << it->second->getName().getStringRef()
328 << "', which replaced the handle";
329 result = failure();
330 }
331 }
332 if (auto r = registerWrittenBy(o))
333 lastWrite[*r] = &o;
334 }
335 });
336 return result;
337}
338
339struct AIECertVerifyPass
340 : xilinx::AIEX::impl::AIECertVerifyBase<AIECertVerifyPass> {
341 void runOnOperation() override {
342 AIE::DeviceOp device = getOperation();
343 if (failed(checkJobSlots(device)))
344 signalPassFailure();
345 if (failed(checkGroupIds(device)))
346 signalPassFailure();
347 if (failed(checkLocalBarrierColocation(device)))
348 signalPassFailure();
349 if (failed(checkWaitTctsUniqueness(device)))
350 signalPassFailure();
351 if (failed(checkPreemptConsistency(device)))
352 signalPassFailure();
353 if (failed(checkRemoteBarrierParties(device)))
354 signalPassFailure();
355 if (failed(checkUcDmaWaitHandles(device)))
356 signalPassFailure();
357 }
358};
359
360} // namespace
361
362std::unique_ptr<OperationPass<AIE::DeviceOp>> AIEX::createAIECertVerifyPass() {
363 return std::make_unique<AIECertVerifyPass>();
364}
virtual uint32_t getNumControllers() const
Total number of microcontrollers (uC) in the device.
std::unique_ptr< mlir::OperationPass< AIE::DeviceOp > > createAIECertVerifyPass()