MLIR-AIE 1.4.6.dev
AIEUtils.h
Go to the documentation of this file.
1//===- AIEUtils.h -----------------------------------------------*- C++ -*-===//
2//
3// Copyright (C) 2025 Advanced Micro Devices, Inc.
4// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
5//
6//===----------------------------------------------------------------------===//
7
8#ifndef AIEX_UTILS_H
9#define AIEX_UTILS_H
10
13#include "mlir/Dialect/MemRef/IR/MemRef.h"
14#include "mlir/IR/BuiltinOps.h"
15#include "mlir/IR/Value.h"
16#include "llvm/ADT/DenseMap.h"
17
18#include "llvm/Support/raw_ostream.h"
19
20#include <map>
21
22using namespace mlir;
23
24namespace xilinx {
25namespace AIEX {
26
27// The private constant `memref.global`s holding a device's blockwrite payloads:
28// one per distinct payload, each new one named `<prefix><n>` past every symbol
29// of that form the device held when the table was made. It holds op handles,
30// so it lives no longer than one rewrite of the device.
32public:
33 BlockwriteData(AIE::DeviceOp dev, llvm::StringRef prefix);
34
35 // The global holding `words`, created at `builder`'s insertion point if the
36 // device has none.
37 memref::GlobalOp getOrCreate(OpBuilder &builder, mlir::Location loc,
38 ArrayRef<uint32_t> words);
39
40 AIE::DeviceOp getDevice() const { return dev; }
41
42private:
43 AIE::DeviceOp dev;
44 std::string prefix;
45 llvm::DenseMap<mlir::Attribute, memref::GlobalOp> byValue;
46 unsigned nextId = 0;
47};
48
49// Result of tracing through supported view/cast operations to a block argument
50// for traceSubviewToBlockArgument function.
52 BlockArgument rootArg;
54};
55
56// Trace through memref.subview, memref.view, memref.cast, and
57// memref.reinterpret_cast operations until the referenced SSA value is a block
58// argument.
59//
60// Returns the root block argument and cumulative byte offset, or std::nullopt
61// if the chain doesn't lead to a block argument or contains unsupported ops.
62//
63// This function checks that all subviews remain static and contiguous. A
64// memref.view must have a constant byte shift and no dynamic result sizes.
65std::optional<SubviewTraceResult> traceSubviewToBlockArgument(Value value);
66
67// Index of `arg` among the host buffers of its runtime sequence.
68//
69// The host passes one buffer per memref argument. Scalar arguments travel in
70// the instruction stream and occupy no buffer slot. The block-argument number
71// therefore over-counts them. Returns nullopt when `arg` is not a memref.
72std::optional<unsigned> getHostBufferArgIndex(BlockArgument arg);
73
74// The number of host buffers `block`'s arguments take: its memref arguments.
75unsigned getHostBufferCount(Block &block);
76
77// The bytes one step of a BD address field covers on tile (`col`, `row`):
78// a shim NOC BD addresses bytes, others the address-generation granule.
79uint64_t getBdAddressUnit(const AIE::AIETargetModel &targetModel, int col,
80 int row);
81
82// Emit an `aiex.npu.update_from_scratchpad` op that adds the runtime offset
83// (held in the scratchpad slot referenced by `bdOp`'s
84// `offset_state_table_idx` attribute, in elements of `bufType`) into the
85// address field of the BD at `registerAddr` on tile (`col`, `row`).
86// `staticByteAddress` is the buffer's address the BD was written with, where
87// known, and `lengthField` the value of its length field, an i32 where it is
88// known only at run time.
90 OpBuilder &builder, Operation *bdOp, BaseMemRefType bufType,
91 uint64_t registerAddr, const AIE::AIETargetModel &targetModel, int col,
92 int row, std::optional<uint64_t> staticByteAddress = std::nullopt,
93 OpFoldResult lengthField = {});
94
95// Emit an `aiex.npu.update_from_scratchpad` op that adds the runtime length
96// (held in the scratchpad slot referenced by `bdOp`'s
97// `length_state_table_idx` attribute, times `lengthUnit` elements of
98// `bufType`) into the buffer length register of BD `bdId` on tile
99// (`col`, `row`), which the firmware counts in 32-bit words. Fails if the tile
100// does not support a runtime length.
101LogicalResult
102emitUpdateBdLengthFromParameter(OpBuilder &builder, Operation *bdOp,
103 BaseMemRefType bufType, int64_t lengthUnit,
104 const AIE::AIETargetModel &targetModel, int col,
105 int row, int bdId);
106
107// The configures a DMA task value can come from. A task carried through
108// runtime control flow is an scf.for iter_arg or an scf.for/scf.if result
109// rather than a configure result; this walks such a value back through every
110// region-branch operand that can feed it (a loop's init and back-edge, each
111// branch's yield), at any nesting depth. Each configure is listed once.
112// Returns false if some path ends at a value that is not a configure result.
113bool getReachableConfigures(Value task,
114 SmallVectorImpl<DMAConfigureTaskOp> &configures);
115
116// The one configure a task value can come from, through runtime control flow
117// as above, or null if there is none or more than one.
118DMAConfigureTaskOp getUniqueReachableConfigure(Value task);
119
120// The tile a runtime-sequence DMA op programs: an aiex.dma_configure_task's
121// own, or for an aiex.dma_configure_task_for or aiex.npu.dma_memcpy_nd, the
122// tile of the shim DMA allocation or route endpoint its symbol names, or the
123// shim end of the objectFIFO it names before allocation. Logical before
124// placement; null for any other op or symbol.
125Operation *getRuntimeDmaTile(Operation *op, SymbolTable &symbols);
126
127// Calls `pinned` for each BD id the runtime sequences of `device` fix at
128// compile time, in IR order, with the tile getRuntimeDmaTile gives; a static BD
129// on that tile must not take one. `channel` is unset until allocation.
131 AIE::DeviceOp device,
132 llvm::function_ref<void(Operation *op, Operation *tile,
133 std::optional<int> channel, int32_t id)>
134 pinned);
135
136// How many times `op` runs when its core, or runtime sequence, runs to
137// completion: the product of the static trip counts of the `scf.for` loops
138// around it, whatever their size. Anything else between the op and the core,
139// an `scf.if`, an `scf.while` (forever included), a loop with dynamic bounds,
140// a block reached by branching or a product that overflows, makes it unknown.
141std::optional<int64_t> staticExecutions(Operation *op);
142
143// Bytes as a linear form in a sequence's scratchpad parameters, each at least
144// 0: the constant at key -1, each parameter's coefficient at its state-table
145// index.
146using Volume = std::map<int64_t, int64_t>;
147
148// Whether a * scaleA <= b * scaleB whatever values the parameters take.
149bool atMost(const Volume &a, int64_t scaleA, const Volume &b, int64_t scaleB);
150
151// Whether `bytes` is a multiple of `granule` (when nonzero) whatever values the
152// parameters take.
153bool wholeGranules(const Volume &bytes, int64_t granule);
154
155// Why the bytes a shim input sent may not all be proven taken by the bytes its
156// consumed_by output received.
157enum class Unbalanced {
159 // A push of either moves bytes no count follows: a parameter not held
160 // non-negative, a chain, or a loop of a dynamic-pool sequence.
162 // Other traffic shares their channels.
164 // The input moves more than the output proves taken.
166 // The output may end partway through an object of the join its proof
167 // passes, whose later segments it has then taken less of.
169};
170
171// Whether `in` bytes sent through a shim input are all taken once `out` bytes
172// came through `proof`'s output: No, PartGranule or Excess.
173Unbalanced balanceUnder(AIE::ConsumedByAttr proof, const Volume &in,
174 const Volume &out);
175
176// Whether `op`, or an op nested in it, names a route end of the objectFIFO
177// `fifo` by symbol.
178bool namesFifo(Operation *op, StringRef fifo, SymbolTableCollection &symbols);
179
180// One step of a runtime sequence that changes the array's configuration.
182 Operation *op;
183 // A PDI load, which resets the array unless the firmware skips it as the
184 // PDI it loaded last.
185 NpuLoadPdiOp load;
186 // A reset the firmware never skips.
187 bool resets = false;
188 AIE::DeviceOp configures;
189};
190
191// Verifies that a buffer resident on a global finds the data the last
192// configuration holding that global left: no reset between them. `steps` are
193// `seq`'s, in program order; the array starts configured as `seq`'s own device,
194// and the host runs `seq` again from its first step on each dispatch.
195LogicalResult checkResidentsSurvive(AIE::RuntimeSequenceOp seq,
196 ArrayRef<ConfigStep> steps);
197
198// `device:sequence`, the name a host runs `seq` by.
199std::string scratchpadCommandName(AIE::RuntimeSequenceOp seq);
200
201// Write params.txt for every `aiex.scratchpad_parameter` in `moduleOp`, one
202// entry per line: `<num_parameters> <num_slots>`, then per parameter `<name>
203// <state_table_idx> <type> <kind> <min> <max>`; `<num_joint_bounds>`, then per
204// bound `<length> <offset> <length_step> <max>`; `<num_commands>`, then per
205// command `<device>:<sequence> <num_read> <name>...`. A slot of "-" means no
206// command reads the parameter. kind is core (shift-2 encoded), addr (raw) or
207// repeat; "- -" bounds mean unbounded. A joint bound requires offset +
208// length_step * length <= max. A command's slots are distinct; commands may
209// share slots. See runtime_lib/test_lib/parameter_scratchpad.h for the parser.
210void emitScratchpadParamsFile(mlir::ModuleOp moduleOp, llvm::raw_ostream &os);
211} // namespace AIEX
212} // namespace xilinx
213
214#endif // AIEX_UTILS_H
memref::GlobalOp getOrCreate(OpBuilder &builder, mlir::Location loc, ArrayRef< uint32_t > words)
Definition AIEUtils.cpp:187
BlockwriteData(AIE::DeviceOp dev, llvm::StringRef prefix)
Definition AIEUtils.cpp:168
AIE::DeviceOp getDevice() const
Definition AIEUtils.h:40
unsigned getHostBufferCount(Block &block)
Definition AIEUtils.cpp:162
void forEachRuntimePinnedBdId(AIE::DeviceOp device, llvm::function_ref< void(Operation *op, Operation *tile, std::optional< int > channel, int32_t id)> pinned)
Definition AIEUtils.cpp:599
uint64_t getBdAddressUnit(const AIE::AIETargetModel &targetModel, int col, int row)
Definition AIEUtils.cpp:207
LogicalResult checkResidentsSurvive(AIE::RuntimeSequenceOp seq, ArrayRef< ConfigStep > steps)
Definition AIEUtils.cpp:396
DMAConfigureTaskOp getUniqueReachableConfigure(Value task)
Definition AIEUtils.cpp:563
bool namesFifo(Operation *op, StringRef fifo, SymbolTableCollection &symbols)
Definition AIEUtils.cpp:386
std::optional< SubviewTraceResult > traceSubviewToBlockArgument(Value value)
Definition AIEUtils.cpp:25
std::optional< int64_t > staticExecutions(Operation *op)
Definition AIEUtils.cpp:329
Operation * getRuntimeDmaTile(Operation *op, SymbolTable &symbols)
Definition AIEUtils.cpp:578
bool atMost(const Volume &a, int64_t scaleA, const Volume &b, int64_t scaleB)
Definition AIEUtils.cpp:354
bool wholeGranules(const Volume &bytes, int64_t granule)
Definition AIEUtils.cpp:371
std::string scratchpadCommandName(AIE::RuntimeSequenceOp seq)
Definition AIEUtils.cpp:451
LogicalResult emitUpdateBdAddressFromOffsetParameter(OpBuilder &builder, Operation *bdOp, BaseMemRefType bufType, uint64_t registerAddr, const AIE::AIETargetModel &targetModel, int col, int row, std::optional< uint64_t > staticByteAddress=std::nullopt, OpFoldResult lengthField={})
Definition AIEUtils.cpp:214
void emitScratchpadParamsFile(mlir::ModuleOp moduleOp, llvm::raw_ostream &os)
std::map< int64_t, int64_t > Volume
Definition AIEUtils.h:146
bool getReachableConfigures(Value task, SmallVectorImpl< DMAConfigureTaskOp > &configures)
Definition AIEUtils.cpp:527
LogicalResult emitUpdateBdLengthFromParameter(OpBuilder &builder, Operation *bdOp, BaseMemRefType bufType, int64_t lengthUnit, const AIE::AIETargetModel &targetModel, int col, int row, int bdId)
Definition AIEUtils.cpp:296
std::optional< unsigned > getHostBufferArgIndex(BlockArgument arg)
Definition AIEUtils.cpp:149
Unbalanced balanceUnder(AIE::ConsumedByAttr proof, const Volume &in, const Volume &out)
Definition AIEUtils.cpp:377
AIE::DeviceOp configures
Definition AIEUtils.h:188