AIEX Passes

-aie-assign-runtime-sequence-bd-ids

Assign IDs to Buffer Descriptors Configured in the Runtime Sequence

-aie-create-cores

Create CoreOp, MemOp, and FlowOp of AIE dialect

Lower toplevel 'call' operations with implicit data movement into aie.core, aie.mem, and aie.flow operations with explicit data movement. The tile tile associated with the operations is inferred based on the aie.x and aie.y attributes of the call operation. e.g.:

func.func @aie_task(%arg0: memref<256xi32>, %arg1: i32) -> () {
  ...
  return
}
%a = constant 0 : i32
func.call @aie_task(%buf, %a) { aie.x = 1, aie.y = 1 } : (memref<256xi32>, i32) -> ()

will result in:

%0 = AIE.tile(1, 1)
%1 = AIE.buffer(%0) : memref<256xi32>
%2 = AIE.buffer(%0) : memref<1xi32>
%c0_i32 = constant 0 : i32
%5 = AIE.core(%0) {
  ...
}

In this case, each argument to aie_task results in an explicit buffer accessed by the core.

-aie-create-locks

Generate physical lock ops from logical lock (token) ops

Tokens represent high-level buffer synchronization through a sequence of pipeline stages. This pass lowers token operations into physical aie.lock operations.

-aie-ctrl-packet-infer-tiles

Infer aie.tile ops from aiex.control_packet addresses

-aie-ctrl-packet-to-dma

Lowers npu.control_packet op to npu.dma_memcpy_nd op

-aie-decompose-large-dma-bd

Decompose oversized non-contiguous ND DMA transfers

Splits aiex.npu.dma_memcpy_nd ops and task-path aie.dma_bd ops (inside aiex.dma_configure_task / aiex.dma_configure_task_for) whose constant ND wrap/stride encoding exceeds the hardware buffer-descriptor field limits (and that cannot be linearized because the access is non-contiguous) into one or more hardware-legal ND transfers that move exactly the same data.

On the task path, multiple sub-patterns are linked with aie.next_bd blocks inside the configure region; bd_id / next_bd_id are left for later passes to assign.

Two techniques are used: dimension factoring (split an oversized dimension of size N=a*b across a free dimension slot) is preferred, falling back to slicing an oversized dimension into ceil(N/limit) sub-transfers with adjusted offsets. Contiguous oversized patterns are left untouched; they are handled by canonicalization to linear mode.

-aie-dma-tasks-to-npu

Lower configured DMA tasks to NPU instructions

-aie-dma-to-npu

-aie-expand-load-pdi

Expand load_pdi operations to explicit configuration sequences

This pass transforms load_pdi { device_ref = @device } operations.

By default (ctrl-pkt = false), each op is replaced with: 1. A load_pdi { device_ref = @empty_N } op (loading an empty device, which causes a device reset). 2. A sequence of aiex.npu.write32/aiex.npu.blockwrite ops that configure the device.

With ctrl-pkt = true, each op is replaced with: 1. A load_pdi { device_ref = @ctrl_pkt_overlay } op, which loads the column control packet overlay needed to stream further configuration as control packets. 2. A sequence of aiex.npu.control_packet ops that configure the device.

The configuration operations are generated by converting the referenced device's configuration to a transaction binary and then disassembling it into MLIR operations.

This pass is intended to run after runtime sequence materialization (i.e., after aiex.configure ops have been turned into aiex.npu.load_pdi).

Options

-ctrl-pkt : If true, lower each load_pdi to an @ctrl_pkt_overlay load_pdi followed by aiex.npu.control_packet ops instead of write32/blockwrite ops with an empty-device reset.

-aie-inline-trace-config

Inline trace configuration and generate NPU writes

Replaces aie.trace.start_config operations by: 1. Looking up the referenced trace.config symbol 2. Resolving register/field names using RegisterDatabase 3. Encoding bitfield values 4. Merging multiple field writes to same register 5. Generating aiex.npu.write32 operations with col/row preserved

-aie-legalize-ctrl-packet

Legalize control packet operations for target

-aie-lower-broadcast-packet

Replace combination of broadcast and packet-switch by packet-flow

Replace combination of broadcast and packet-switch by packet-flow

-aie-lower-core-reset

Lowers all aiex.core_reset operations to npu.maskwrite32

-aie-lower-dma-channel-reset

Lowers aiex.dma_channel_reset(_for) to npu.maskwrite32 + re-arm

Two concerns, one pass (kept together like the other reset lowerings):

• Each aiex.dma_channel_reset_for @fifo is first expanded, via the fifo's aie.objectfifo_rearm_binding, into the resident re-arm of its non-shim channels: an aiex.dma_channel_reset per channel, an aiex.set_lock per producer/consumer lock, and an aiex.npu.push_queue START_QUEUE re-push per channel (head BD id + repeat read straight off the binding, populated by --aie-assign-bd-ids).
• Every aiex.dma_channel_reset -- standalone or just emitted above -- is then lowered to the aiex.npu.maskwrite32 reset pulse.

The emitted set_lock / push_queue are lowered later by --aie-lower-set-lock / --aie-dma-to-npu, so run this before them.

-aie-lower-dynamic-bd-pool

Lower runtime-bound DMA task allocation to a runtime BD free-list pool

The dynamic counterpart to aie-assign-runtime-sequence-bd-ids. That pass requires straight-line IR and rejects runtime-bound scf.for; this pass handles the runtime-bound case by keeping the loop rolled and drawing buffer descriptor IDs from a per-tile runtime free-list pool.

For each dma_configure_task it inserts an aiex.dma_bd_pool_pop and routes the popped SSA bd_id into the BD's lowering; each dma_free_task and the recycling half of a dma_await_task becomes an aiex.dma_bd_pool_push of the matching ID (matched through the def-use / scf.for iter_args chain).

Runs only on the dynamic EmitC path, after aie-unroll-runtime-sequence- loops has removed every constant-trip loop, so any surviving scf.for is genuinely runtime-bound. v1 supports single-BD tasks; multi-BD chains under a runtime loop are diagnosed.

-aie-lower-memcpy

Lower aie.memcpy operations to Flows and DMA programs

aie.memcpy operations are an experimental high-level abstraction which move data from one buffer to another. This pass lowers them into appropriate aie.flow and aie.mem operations.

-aie-lower-multicast

Lower AIE.multicast operation to AIE.flow operations

This pass replaces AIE.multicast operation with the equivalent number of AIE.flow operations. The lowered AIE.flow operations have the same source port but different destinations.

-aie-lower-scratchpad-parameters

Lower scratchpad parameter ops and emit parameter-sync preambles

Lowers aiex.scratchpad_parameter and aiex.read_scratchpad_parameter ops into concrete scratchpad-based communication between host and AIE cores.

Assigns globally-unique state table indices to every aiex.scratchpad_parameter in the module (indices in [0, 32), since the scratchpad is a single hardware resource shared by all PDIs loaded by a runtime sequence). Creates per-core buffers for each aiex.read_scratchpad_parameter usage. Automatically emits a parameter-sync preamble driven by the emit_parameter_sync_preamble attribute on aie.core and aie.runtime_sequence: - In each qualifying core: inserts aie.lock + aie.use_lock(Acquire, 1). - In each qualifying runtime sequence: inserts aiex.npu.create_scratchpad, per-parameter aiex.npu.write32 + aiex.npu.update_from_scratchpad, and aiex.set_lock for each core lock.

Sets a kind attribute on each aiex.scratchpad_parameter based on how it is used: core if read by aiex.read_scratchpad_parameter, addr if used as a DMA offset_parameter. A parameter may not be used as both.

Optionally emits a params.txt file describing every parameter in the module (name, global state_table_idx, type, and kind).

Options

-output-params-file : Path to write the parameter layout file to.

-aie-lower-set-lock

Lowers all aiex.set_lock operations to npu.write32Op

-aie-materialize-bd-chains

Concretize aie.bd_chain ops at aiex.start_task use sites

Inlines pre-defined aie.bd_chains at aiex.start_task use sites to become aiex.dma_configure_task and aiex.dma_start_task ops.

-aie-materialize-runtime-sequences

Turn aiex.configure into configuration primitives and inline aiex.run calls

Turns top-level aiex.configure into load PDI firmware instructions that set up the requested configuration.

Inlines calls to other runtime sequences using aiex.run into the calling runtime sequence, resolving references within them to the device containing the definition.

This pass requires ObjectFIFOs to be lowered first; apply the ObjectFIFO stateful transform before applying this pass.

-aie-npu-to-cert

Transform aiex.npu operations to aiex.cert operations

This pass transforms low level aiex.npu operations contained in aie.runtime_sequence operations into aiex.cert operations enclosed in aiex.cert.job operations. The write32, maskwrite32, blockwrite and sync operations are supported.

Referenced devices are absorbed into cert.section operations and removed from the output, keeping only the main device.

Options

-device-name : Name of the main device to emit (other devices are removed after absorption)

-aie-scf-to-control-flow

Lower scf to cf everywhere except inside runtime sequences

Converts structured control flow (scf) to unstructured control flow (cf) throughout the module, with one exception: scf operations nested inside an aie.runtime_sequence are left untouched.

A runtime sequence is NoTerminator and is lowered to a flat NPU instruction stream that has no notion of branches; its loops are instead resolved by the dedicated runtime-sequence lowering path (loop unrolling for compile-time-constant trip counts, or the dynamic EmitC path otherwise). Running the generic convert-scf-to-cf over a runtime sequence would both violate its NoTerminator block invariant (the ops following a lowered loop end up in a terminator-less block) and feed the flat NPU emitter control-flow ops it silently drops -- a miscompile.

This pass is therefore a drop-in replacement for convert-scf-to-cf in pipelines that contain runtime sequences: core/host scf is lowered to cf as usual (e.g. before aie-standard-lowering), while runtime-sequence control flow is preserved for its own lowering.

-aie-substitute-shim-dma-allocations

Replace symbolic references to aie.shim_dma_allocation ops with their (tile, direction, channel) triple

-aie-transform-bfp-types

Transform bfp types to standard builtin types

Lowers bfp types to standard builtin types. Adapts operations as necessary to accomodate for bfp data movement.

-aie-txn-to-ctrl-packet

Convert transaction operations to control packet operations

-aie-unroll-runtime-sequence-loops

Unroll constant-bound loops in runtime sequences

Fully unrolls scf.for loops with compile-time-constant trip counts that appear inside aie.runtime_sequence bodies.

Runs before aie-assign-runtime-sequence-bd-ids so BD-ID allocation sees straight-line IR: configure operations in each loop iteration can receive individual BD IDs after unrolling.

Runtime-bound loops (non-constant trip count) are left in place for the dynamic EmitC lowering path.

-aie-verify-runtime-rearm

Experimental, opt-in: reject an aiex.dma_channel_reset whose objectFIFO lock is never re-armed (a necessary, not sufficient, condition for a safe reset)

-aiex-standard-lowering

Lower AIEX operations

AIEX Npu Ops are removed.

-cert-legalize-pages

Split cert jobs to fit into 8k pages

This pass splits cert jobs into smaller jobs that fit into 8k pages. It is used to ensure that the generated code does not exceed the page size limit of the aiebu tools and cert firmware.