Add C ObjectFIFO API for kernel-managed lock synchronization

[jgmelber]

Enable precompiled C kernels to directly manage ObjectFIFO synchronization by receiving lock IDs and buffer references from MLIR, rather than relying on the compiler to insert acquire/release ops.

New MLIR ops:

• aie.objectfifo.lock: returns (acq_lock, rel_lock) for a port
• aie.objectfifo.buffer: returns a buffer memref at a given index

Stateful transform lowering resolves these ops to concrete lock/buffer SSA values, handling AIE1 single-lock and AIE2/AIE2P dual-lock semantics.

C API header (aie_runtime_lib/AIE2{,P}/aie_objectfifo.h): objectfifo_port_t struct with inline acquire/release functions using compiler-provided lock intrinsics. Use acq_value=-1 for AcquireGreaterEqual semantics matching the DMA protocol.

Python API: get_lock()/get_buffer() on object_fifo and ObjectFifoHandle.

Bug fixes discovered during hardware bring-up:

• python/dialects/aie.py: get_lock() passed incorrect extra args to ObjectFifoGetLockOp auto-generated constructor
• AIELocalizeLocks: used getParentOp() == coreOp which failed for lock uses nested inside scf.for; fixed to use isProperAncestor()

Includes:

• CMake install rules for aie_objectfifo.h into install tree
• LIT tests for lock localization with external function calls
• E2E NPU tests (lock_pass_to_c, objectfifo_lock_c_api)
• Programming example: passthrough_kernel_c_objfifo

[jgmelber]

Related to #288

[github-actions]

Coverage Report

Created: 2026-03-03 03:40

Click here for information about interpreting this report.

Filename	Function Coverage	Line Coverage	Region Coverage	Branch Coverage
IR/AIEDialect.cpp	93.28%	86.63%	87.75%	79.19%
Transforms/AIELocalizeLocks.cpp	100.00%	98.11%	94.44%	93.75%
Transforms/AIEObjectFifoStatefulTransform.cpp	100.00%	94.14%	91.61%	85.12%
Totals	95.26%	90.54%	89.38%	81.91%

Generated by llvm-cov -- llvm version 18.1.3

[fifield]

The C-ABI is basically: manually extract locks and buffers from the objectfifo symbol, pass them around in an ad-hoc way, then glue some of them back together into a partial object fifo data structure so that you can call objectfifo-like functions on them.

            out_buf0 = of_out.get_buffer(0)
            out_buf1 = of_out.get_buffer(1)
            out_acq, out_rel = of_out.get_lock(ObjectFifoPort.Produce)

            # C kernel owns the compute loop and buffer rotation
            passThroughLine(
                in_buf0,
                in_buf1,
                out_buf0,
                out_buf1,
                in_acq,
                in_rel,
                out_acq,
                out_rel,
            )

typedef struct {
  int32_t acq_lock; // Lock ID for acquire operation
  int32_t rel_lock; // Lock ID for release operation
  int32_t
      acq_value; // Value for acquire_equal(): use -1 for AcquireGreaterEqual
  int32_t rel_value; // Value for release() call (typically 1)
} objectfifo_port_t;

void passThroughLine(int32_t *in_buf0, int32_t *in_buf1, int32_t *out_buf0,
                     int32_t *out_buf1, int64_t in_acq_lock,
                     int64_t in_rel_lock, int64_t out_acq_lock,
                     int64_t out_rel_lock) {
  objectfifo_port_t port_in = {(int32_t)in_acq_lock, (int32_t)in_rel_lock, -1,
                               1};
  objectfifo_port_t port_out = {(int32_t)out_acq_lock, (int32_t)out_rel_lock,
                                -1, 1};
    
    // ...

    objectfifo_acquire(&port_in);
    objectfifo_acquire(&port_out);

Did you consider instead of objectfifo_port_t an objectfifo_t which also includes the buffers? This could be a defacto C compatible ABI for passing around object fifos analogous to the numpy array struct format memrefs lower to.

            # C kernel owns the compute loop and buffer rotation
            passThroughLine(of_out.get_value())

typedef struct {
  // some well defined layout
  // ports ...
  // buffers ...
} objectfifo_t;

void passThroughLine(objectfifo_t *of) {
    // ...

    objectfifo_acquire(Consume, of);
    objectfifo_acquire(Produce, of);

[jgmelber]

Did you consider instead of objectfifo_port_t an objectfifo_t which also includes the buffers? This could be a defacto C compatible ABI for passing around object fifos analogous to the numpy array struct format memrefs lower to.

            # C kernel owns the compute loop and buffer rotation
            passThroughLine(of_out.get_value())

typedef struct {
 // some well defined layout
 // ports ...
 // buffers ...
} objectfifo_t;

void passThroughLine(objectfifo_t *of) {
   // ...

   objectfifo_acquire(Consume, of);
   objectfifo_acquire(Produce, of);

Yes, I was thinking of something along those lines. It gets messy handling those buffers from the user perspective. The struct should also know how deep the objFIFO is so that it can do the % or better a +/- to access the objects in the correct order.

[jgmelber]

This PR needs more npu-xrt tests: depth 1 and 3