MLIR-AIE 1.4.6.dev
parameter_scratchpad.h
Go to the documentation of this file.
1//===- parameter_scratchpad.h - Host-side parameter runtime ------*- C++-*-===//
2//
3// Copyright (C) 2026 Advanced Micro Devices, Inc.
4// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
5//
6//===----------------------------------------------------------------------===//
7//
8// ParameterScratchpad: Host-side runtime class for writing named parameters
9// to AIE cores via the scratchpad mechanism.
10//
11// Usage:
12// auto params = test_utils::ParameterScratchpad(run, "params.txt");
13// params.write("foo", 42u);
14// params.write("bar", std::bfloat16_t(3.14f));
15// params.sync();
16//
17// A module of several commands, runtime sequences no `aiex.run` calls, gives
18// each its own scratchpad, in which parameters of different commands may
19// share a slot: construct each command's with its `device:sequence` name, and
20// write it with that command's parameters (`names()`) only. With no name, the
21// module must have one command.
22//
23//===----------------------------------------------------------------------===//
24
25#ifndef AIE_RUNTIME_TEST_LIB_PARAMETER_SCRATCHPAD_H
26#define AIE_RUNTIME_TEST_LIB_PARAMETER_SCRATCHPAD_H
27
28#include <cstdint>
29#include <cstring>
30#include <fstream>
31#include <stdexcept>
32#include <string>
33#include <unordered_map>
34#include <unordered_set>
35#include <utility>
36#include <vector>
37
38#if !defined(TEST_UTILS_USE_XRT)
39#if defined(__has_include) && __has_include(<xrt/xrt_bo.h>) && \
40 __has_include(<xrt/xrt_kernel.h>)
41#define TEST_UTILS_USE_XRT 1
42#else
43#define TEST_UTILS_USE_XRT 0
44#endif
45#endif
46
47#if TEST_UTILS_USE_XRT
48#include <xrt/xrt_bo.h>
49#include <xrt/xrt_kernel.h>
50#endif
51
52namespace test_utils {
53
55public:
56#if TEST_UTILS_USE_XRT
57 /// Construct from an XRT run handle (C++ usage), for the parameters of
58 /// `command` (`device:sequence`), or of the module's one command when it
59 /// is empty.
60 ParameterScratchpad(xrt::run &run, const std::string &paramsPath,
61 const std::string &command = "") {
62 parseParams(paramsPath);
63 selectCommand(command, paramsPath);
64 scratchpadBo = run.get_ctrl_scratchpad_bo();
65 boMap = scratchpadBo.map<uint32_t *>();
66 if (scratchpadBo.size() < scratchpadSizeBytes)
67 throw std::runtime_error("ParameterScratchpad: BO size (" +
68 std::to_string(scratchpadBo.size()) +
69 ") < required scratchpad size (" +
70 std::to_string(scratchpadSizeBytes) + ")");
71 clear();
72 }
73#endif
74
75 /// Construct from a raw buffer and its size in bytes (Python bindings /
76 /// testing). The size is required: clear() and every write index off
77 /// scratchpadSizeBytes, which parseParams derives from the params file, not
78 /// from the buffer.
79 ParameterScratchpad(uint32_t *buffer, size_t bufferSizeBytes,
80 const std::string &paramsPath,
81 const std::string &command = "")
82 : boMap(buffer) {
83 parseParams(paramsPath);
84 selectCommand(command, paramsPath);
85 if (bufferSizeBytes < scratchpadSizeBytes)
86 throw std::runtime_error("ParameterScratchpad: buffer size (" +
87 std::to_string(bufferSizeBytes) +
88 ") < required scratchpad size (" +
89 std::to_string(scratchpadSizeBytes) + ")");
90 clear();
91 }
92
93 /// Write raw bytes (up to 4) by name, interpreted as a little-endian
94 /// uint32. For core-kind parameters, the bits are left-shifted by 2
95 /// (firmware requirement); for repeat-kind ones, by 16 (into the task
96 /// queue's repeat field).
97 /// For addr-kind parameters, the value is written raw (no shift).
98 void writeBytes(const std::string &name, const void *data, size_t len) {
99 uint32_t bits = 0;
100 std::memcpy(&bits, data, std::min(len, sizeof(bits)));
101 writeBits(name, bits);
102 }
103
104 /// Write a raw 32-bit value by name. For core-kind parameters, the bits
105 /// are left-shifted by 2 (firmware requirement); for repeat-kind ones, by
106 /// 16 (into the task queue's repeat field). For addr-kind parameters,
107 /// the value is written directly (no shift). A DMA offset or length
108 /// parameter's value, read as an int32, must lie in the range the compiler
109 /// gave it, which keeps its transfers within their buffers; a repeat
110 /// parameter's, at most its task's repeat count. An offset into elements
111 /// narrower than 4 bytes must be a multiple of the elements in a word, or
112 /// the DMA would round its address down.
113 void writeBits(const std::string &name, uint32_t bits) {
114 if (unslotted.count(name))
115 throw std::runtime_error("ParameterScratchpad: no command reads "
116 "parameter '" +
117 name + "', so it has no slot");
118 auto it = paramMap.find(name);
119 if (it == paramMap.end()) {
120 throw std::runtime_error("ParameterScratchpad: unknown parameter '" +
121 name + "'");
122 }
123 if (!members.count(name))
124 throw std::runtime_error("ParameterScratchpad: command '" + command +
125 "' does not read parameter '" + name +
126 "', whose slot another of its parameters may "
127 "hold");
128 if (auto multiple = offsetMultiples.find(name);
129 multiple != offsetMultiples.end() &&
130 static_cast<int32_t>(bits) % multiple->second)
131 throw std::invalid_argument(
132 "ParameterScratchpad: value " +
133 std::to_string(static_cast<int32_t>(bits)) + " of '" + name +
134 "' is not a multiple of " + std::to_string(multiple->second) +
135 " elements, which the DMA address it offsets needs to stay "
136 "4-byte aligned");
137 if (auto range = ranges.find(name); range != ranges.end()) {
138 int32_t value = static_cast<int32_t>(bits);
139 if (value < range->second.first || value > range->second.second)
140 throw std::invalid_argument(
141 "ParameterScratchpad: value " + std::to_string(value) + " of '" +
142 name + "' is outside [" + std::to_string(range->second.first) +
143 ", " + std::to_string(range->second.second) + "], " +
144 (repeatParams.count(name)
145 ? "its task's largest repeat count"
146 : "which keeps its DMA transfers within their buffers"));
147 values[name] = value;
148 }
149 uint8_t idx = it->second;
150 uint32_t encoded = bits;
151 if (coreParams.count(name)) {
152 // core parameters require shift-2 to survive masking of lowest bits by
153 // firmware op
154 encoded = bits << 2;
155 } else if (repeatParams.count(name)) {
156 encoded = bits << 16;
157 }
158 boMap[idx] = encoded;
159 }
160
161 /// Write a typed parameter value. For core-kind parameters, the raw bits
162 /// are left-shifted by 2 as required by the firmware's UPDATE_REG Incr mode,
163 /// and the core right-shifts (unsigned) by 2 after reading. The round trip
164 /// therefore zeroes the top 2 bits of the value (the bottom 2 bits are
165 /// preserved). Types that fit in 30 bits (e.g. uint16_t, int16_t,
166 /// std::bfloat16_t, and uint32_t values < 2^30) round-trip losslessly.
167 /// `float` is not supported as a core-kind parameter (the verifier in
168 /// `--aie-lower-scratchpad-parameters` rejects it).
169 template <typename T>
170 void write(const std::string &name, T value) {
171 static_assert(sizeof(T) <= 4, "Parameter values must be at most 32 bits");
172 uint32_t bits = 0;
173 std::memcpy(&bits, &value, sizeof(T));
174 writeBits(name, bits);
175 }
176
177 /// Check the written values of each offset and length parameter pair that
178 /// one DMA transfer uses. Throws std::invalid_argument if they take the
179 /// transfer past the end of its buffer.
180 void validate() const {
181 for (const JointBound &bound : jointBounds) {
182 int64_t offset = values.at(bound.offset);
183 int64_t length = values.at(bound.length);
184 int64_t end = offset + bound.lengthStep * length;
185 if (end > bound.max)
186 throw std::invalid_argument(
187 "ParameterScratchpad: '" + bound.offset +
188 "' = " + std::to_string(offset) + " plus " +
189 std::to_string(bound.lengthStep) + " * '" + bound.length +
190 "' = " + std::to_string(length) + " is " + std::to_string(end) +
191 ", above " + std::to_string(bound.max) +
192 ", so a DMA transfer using both runs past its buffer");
193 }
194 }
195
196#if TEST_UTILS_USE_XRT
197 /// Validate, then sync the scratchpad buffer to device. Call after all writes
198 /// for this run.
199 void sync() {
200 validate();
201 scratchpadBo.sync(XCL_BO_SYNC_BO_TO_DEVICE);
202 }
203#endif
204
205 /// The parameters this scratchpad holds: its command's.
206 std::vector<std::string> names() const {
207 return std::vector<std::string>(members.begin(), members.end());
208 }
209
210 /// Read back a parameter's current encoded value (for debugging).
211 uint32_t read(const std::string &name) const {
212 if (unslotted.count(name))
213 throw std::runtime_error("ParameterScratchpad: no command reads "
214 "parameter '" +
215 name + "', so it has no slot");
216 auto it = paramMap.find(name);
217 if (it == paramMap.end()) {
218 throw std::runtime_error("ParameterScratchpad: unknown parameter '" +
219 name + "'");
220 }
221 return boMap[it->second];
222 }
223
224private:
225#if TEST_UTILS_USE_XRT
226 xrt::bo scratchpadBo;
227#endif
228 uint32_t *boMap = nullptr;
229 size_t scratchpadSizeBytes = 0;
230 std::unordered_map<std::string, uint8_t> paramMap;
231 std::unordered_set<std::string> unslotted; // params no command reads
232 std::unordered_set<std::string> coreParams; // params with kind="core"
233 std::unordered_set<std::string> repeatParams; // params with kind="repeat"
234 std::unordered_map<std::string, std::pair<int32_t, int32_t>> ranges;
235 std::unordered_map<std::string, int32_t> values; // of the ranged params
236 // Offset parameters into elements narrower than a word, by the element
237 // count whose bytes fill one.
238 std::unordered_map<std::string, int32_t> offsetMultiples;
239 struct JointBound {
240 std::string length, offset;
241 int64_t lengthStep, max;
242 };
243 std::vector<JointBound> jointBounds;
244 // Each command's parameters, by `device:sequence`.
245 std::unordered_map<std::string, std::unordered_set<std::string>> commands;
246 std::vector<std::string> commandNames; // in params.txt order
247 std::string command;
248 std::unordered_set<std::string> members;
249
250 void selectCommand(const std::string &name, const std::string &path) {
251 command = name;
252 if (name.empty()) {
253 if (commandNames.empty())
254 throw std::runtime_error("ParameterScratchpad: '" + path +
255 "' lists no command to hold parameters for");
256 if (commandNames.size() > 1) {
257 std::string available;
258 for (const std::string &entry : commandNames)
259 available += (available.empty() ? "" : ", ") + entry;
260 throw std::runtime_error(
261 "ParameterScratchpad: '" + path + "' lists " +
262 std::to_string(commandNames.size()) +
263 " commands, whose parameters may share slots: name the one this "
264 "scratchpad is for, of " +
265 available);
266 }
267 command = commandNames.front();
268 }
269 auto it = commands.find(command);
270 if (it == commands.end())
271 throw std::runtime_error("ParameterScratchpad: '" + path +
272 "' has no command '" + name + "'");
273 members = it->second;
274 }
275
276 void clear() {
277 for (size_t i = 0; i < scratchpadSizeBytes / 4; i++) {
278 boMap[i] = 0;
279 }
280 }
281
282 void parseParams(const std::string &path) {
283 std::ifstream file(path);
284 if (!file.is_open()) {
285 throw std::runtime_error("ParameterScratchpad: cannot open '" + path +
286 "'");
287 }
288
289 // Format (emitScratchpadParamsFile's):
290 // <num_parameters> <num_slots>
291 // <name> <state_table_idx> <type> <kind> <min> <max>
292 // ...
293 // <num_joint_bounds>
294 // <length> <offset> <length_step> <max>
295 // ...
296 // <num_commands>
297 // <device>:<sequence> <num_read> <name> ...
298 // ...
299 // <num_offset_multiples>
300 // <name> <multiple>
301 // ...
302 // where <state_table_idx> is "-" for a parameter no command reads, kind
303 // is "core", "addr" or "repeat", and <min> <max> is "- -" for a parameter
304 // with no range. A joint bound requires
305 // offset + length_step * length <= max. The offset multiples, absent when
306 // no offset needs one, list the offset parameters whose value must be a
307 // multiple.
308 unsigned numParams = 0, numSlots = 0;
309 file >> numParams >> numSlots;
310 if (!file)
311 throw std::runtime_error(
312 "ParameterScratchpad: missing parameter and slot counts in '" + path +
313 "'");
314 scratchpadSizeBytes = numSlots * 4;
315
316 for (unsigned i = 0; i < numParams; i++) {
317 std::string name, slot, type, kind, min, max;
318 file >> name >> slot >> type >> kind >> min >> max;
319 if (!file)
320 throw std::runtime_error("ParameterScratchpad: malformed entry " +
321 std::to_string(i) + " in '" + path + "'");
322 if (paramMap.count(name) || unslotted.count(name))
323 throw std::runtime_error(
324 "ParameterScratchpad: duplicate parameter name '" + name + "'");
325 if (slot == "-") {
326 unslotted.insert(name);
327 } else {
328 unsigned long idx = 0;
329 try {
330 idx = std::stoul(slot);
331 } catch (const std::logic_error &) {
332 throw std::runtime_error("ParameterScratchpad: malformed slot '" +
333 slot + "' for parameter '" + name +
334 "' in '" + path + "'");
335 }
336 if (idx >= numSlots)
337 throw std::runtime_error("ParameterScratchpad: state_table_idx " +
338 std::to_string(idx) + " for '" + name +
339 "' is past the " + std::to_string(numSlots) +
340 " slots of '" + path + "'");
341 paramMap[name] = static_cast<uint8_t>(idx);
342 }
343 if (kind != "core" && kind != "addr" && kind != "repeat") {
344 throw std::runtime_error("ParameterScratchpad: invalid kind '" + kind +
345 "' for parameter '" + name + "'");
346 } else if (kind == "core") {
347 coreParams.insert(name);
348 } else if (kind == "repeat") {
349 repeatParams.insert(name);
350 }
351 if (min != "-") {
352 try {
353 ranges[name] = {std::stoi(min), std::stoi(max)};
354 } catch (const std::logic_error &) {
355 throw std::runtime_error("ParameterScratchpad: malformed range '" +
356 min + " " + max + "' for parameter '" +
357 name + "' in '" + path + "'");
358 }
359 values[name] = 0;
360 }
361 }
362
363 unsigned numJointBounds = 0;
364 file >> numJointBounds;
365 if (!file)
366 throw std::runtime_error(
367 "ParameterScratchpad: missing joint bound count in '" + path + "'");
368 for (unsigned i = 0; i < numJointBounds; i++) {
369 JointBound bound;
370 file >> bound.length >> bound.offset >> bound.lengthStep >> bound.max;
371 if (!file)
372 throw std::runtime_error("ParameterScratchpad: malformed joint bound " +
373 std::to_string(i) + " in '" + path + "'");
374 for (const std::string &name : {bound.length, bound.offset})
375 if (!ranges.count(name))
376 throw std::runtime_error("ParameterScratchpad: joint bound " +
377 std::to_string(i) + " names '" + name +
378 "', which has no range, in '" + path + "'");
379 jointBounds.push_back(bound);
380 }
381
382 unsigned numCommands = 0;
383 file >> numCommands;
384 if (!file)
385 throw std::runtime_error(
386 "ParameterScratchpad: missing command count in '" + path + "'");
387 for (unsigned i = 0; i < numCommands; i++) {
388 std::string name;
389 unsigned numRead = 0;
390 file >> name >> numRead;
391 commandNames.push_back(name);
392 std::unordered_set<std::string> &reads = commands[name];
393 for (unsigned j = 0; j < numRead; j++) {
394 std::string param;
395 file >> param;
396 if (file && !paramMap.count(param))
397 throw std::runtime_error("ParameterScratchpad: command '" + name +
398 "' names unknown parameter '" + param +
399 "' in '" + path + "'");
400 reads.insert(param);
401 }
402 if (!file)
403 throw std::runtime_error("ParameterScratchpad: malformed command " +
404 std::to_string(i) + " in '" + path + "'");
405 }
406
407 unsigned numMultiples = 0;
408 if (!(file >> numMultiples))
409 return;
410 for (unsigned i = 0; i < numMultiples; i++) {
411 std::string name;
412 int32_t multiple = 0;
413 file >> name >> multiple;
414 if (!file || multiple < 1)
415 throw std::runtime_error("ParameterScratchpad: malformed offset "
416 "multiple " +
417 std::to_string(i) + " in '" + path + "'");
418 if (!paramMap.count(name))
419 throw std::runtime_error("ParameterScratchpad: offset multiple " +
420 std::to_string(i) +
421 " names unknown "
422 "parameter '" +
423 name + "' in '" + path + "'");
424 offsetMultiples[name] = multiple;
425 }
426 }
427};
428
429} // namespace test_utils
430
431#endif // AIE_RUNTIME_TEST_LIB_PARAMETER_SCRATCHPAD_H
void writeBytes(const std::string &name, const void *data, size_t len)
Write raw bytes (up to 4) by name, interpreted as a little-endian uint32.
void writeBits(const std::string &name, uint32_t bits)
Write a raw 32-bit value by name.
void validate() const
Check the written values of each offset and length parameter pair that one DMA transfer uses.
uint32_t read(const std::string &name) const
Read back a parameter's current encoded value (for debugging).
void write(const std::string &name, T value)
Write a typed parameter value.
std::vector< std::string > names() const
The parameters this scratchpad holds: its command's.
ParameterScratchpad(uint32_t *buffer, size_t bufferSizeBytes, const std::string &paramsPath, const std::string &command="")
Construct from a raw buffer and its size in bytes (Python bindings / testing).