Add C ObjectFIFO API for kernel-managed lock synchronization

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

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jgmelber

aie_runtime_lib/AIE2/aie_objectfifo.h

@@ -0,0 +1,63 @@
+//===- aie_objectfifo.h - ObjectFIFO C API for AIE2 -------------*- C++ -*-===//
+//
+// This file is licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (C) 2026, Advanced Micro Devices, Inc.
+//
+//===----------------------------------------------------------------------===//
+//
+// Clean C API for ObjectFIFO acquire/release operations in AIE2 kernels.
+// Hides the dual-lock (producer + consumer) semantics of AIE2 semaphore locks.
+//
+// On AIE2, each ObjectFIFO element has two locks:
+//   - Producer lock (acq_lock for producer, rel_lock for consumer)
+//   - Consumer lock (rel_lock for producer, acq_lock for consumer)
+//
+// The MLIR `aie.objectfifo.lock` op resolves the correct lock IDs for each
+// port and passes them as function arguments. This header provides a struct
+// and inline functions to use them.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef AIE_OBJECTFIFO_H
+#define AIE_OBJECTFIFO_H
+
+#include <stdint.h>
+
+// Lock intrinsics (acquire_equal, release) are provided by the compiler:
+//   - Peano: auto-included via aiev2intrin.h / aie2pintrin.h
+//   - Chess: compiler built-ins
+#ifndef __AIENGINE__
+#error                                                                         \
+    "aie_objectfifo.h must be compiled for an AIE target (__AIENGINE__ not defined)"
+#endif
+
+// ObjectFIFO port handle for C kernels.
+// Encapsulates everything needed to acquire/release from a given port.
+// The MLIR compiler fills in the correct lock IDs and values based on
+// ObjectFIFO configuration and port direction.
+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;
+
+// Acquire an ObjectFIFO port (blocks until available).
+// For producers: waits until the buffer is free to write.
+// For consumers: waits until data is ready to read.
+static inline void objectfifo_acquire(const objectfifo_port_t *port) {
+  acquire_equal(port->acq_lock, port->acq_value);
+}
+
+// Release an ObjectFIFO port.
+// For producers: signals that data has been written.
+// For consumers: signals that the buffer is free.
+static inline void objectfifo_release(const objectfifo_port_t *port) {
+  release(port->rel_lock, port->rel_value);
+}
+
+#endif // AIE_OBJECTFIFO_H

aie_runtime_lib/AIE2P/aie_objectfifo.h

@@ -0,0 +1,63 @@
+//===- aie_objectfifo.h - ObjectFIFO C API for AIE2P ------------*- C++ -*-===//
+//
+// This file is licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (C) 2026, Advanced Micro Devices, Inc.
+//
+//===----------------------------------------------------------------------===//
+//
+// Clean C API for ObjectFIFO acquire/release operations in AIE2P kernels.
+// Hides the dual-lock (producer + consumer) semantics of AIE2P semaphore locks.
+//
+// On AIE2P, each ObjectFIFO element has two locks:
+//   - Producer lock (acq_lock for producer, rel_lock for consumer)
+//   - Consumer lock (rel_lock for producer, acq_lock for consumer)
+//
+// The MLIR `aie.objectfifo.lock` op resolves the correct lock IDs for each
+// port and passes them as function arguments. This header provides a struct
+// and inline functions to use them.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef AIE_OBJECTFIFO_H
+#define AIE_OBJECTFIFO_H
+
+#include <stdint.h>
+
+// Lock intrinsics (acquire_equal, release) are provided by the compiler:
+//   - Peano: auto-included via aiev2intrin.h / aie2pintrin.h
+//   - Chess: compiler built-ins
+#ifndef __AIENGINE__
+#error                                                                         \
+    "aie_objectfifo.h must be compiled for an AIE target (__AIENGINE__ not defined)"
+#endif
+
+// ObjectFIFO port handle for C kernels.
+// Encapsulates everything needed to acquire/release from a given port.
+// The MLIR compiler fills in the correct lock IDs and values based on
+// ObjectFIFO configuration and port direction.
+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;
+
+// Acquire an ObjectFIFO port (blocks until available).
+// For producers: waits until the buffer is free to write.
+// For consumers: waits until data is ready to read.
+static inline void objectfifo_acquire(const objectfifo_port_t *port) {
+  acquire_equal(port->acq_lock, port->acq_value);
+}
+
+// Release an ObjectFIFO port.
+// For producers: signals that data has been written.
+// For consumers: signals that the buffer is free.
+static inline void objectfifo_release(const objectfifo_port_t *port) {
+  release(port->rel_lock, port->rel_value);
+}
+
+#endif // AIE_OBJECTFIFO_H

aie_runtime_lib/CMakeLists.txt

@@ -61,4 +61,10 @@ if(AIETools_AIE2P_FOUND)
   add_subdirectory(AIE2P)
 endif()
 
-
+# Install aie_objectfifo.h unconditionally (no AIETools dependency)
+foreach(arch AIE2 AIE2P)
+  if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/${arch}/aie_objectfifo.h)
+    install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/${arch}/aie_objectfifo.h
+            DESTINATION ${CMAKE_INSTALL_PREFIX}/aie_runtime_lib/${arch})
+  endif()
+endforeach()

include/aie/Dialect/AIE/IR/AIEOps.td

@@ -2038,6 +2038,78 @@ def AIE_ObjectFifoSubviewAccessOp : AIE_Op<"objectfifo.subview.access", []> {
   }];
 }
 
+def AIE_ObjectFifoGetLockOp : AIE_Op<"objectfifo.lock", []> {
+  let summary = "Get acquire and release lock IDs for an ObjectFIFO port";
+  let description = [{
+    Returns the acquire and release lock IDs for the given ObjectFIFO port.
+    These lock IDs can be passed to precompiled C kernels that call
+    `acquire_equal()` / `release()` directly.
+
+    On AIE2 (semaphore locks), each ObjectFIFO element has two locks
+    (producer + consumer). The acquire lock differs from the release lock:
+      - Producer port: acquire = prod_lock, release = cons_lock
+      - Consumer port: acquire = cons_lock, release = prod_lock
+
+    Example:
+    ```
+      %acq_lock, %rel_lock = aie.objectfifo.lock @of1 (Produce) : (index, index)
+    ```
+    The returned `index` values are the localized lock IDs, suitable for passing
+    to external C functions as integer arguments.
+  }];
+
+  let arguments = (
+    ins ObjectFifoPort:$port,
+        FlatSymbolRefAttr:$objFifo_name
+  );
+
+  let results = (outs Index:$acq_lock, Index:$rel_lock);
+
+  let assemblyFormat = [{
+    attr-dict $objFifo_name `(` $port `)` `:` `(` type($acq_lock) `,` type($rel_lock) `)`
+  }];
+
+  let hasVerifier = 1;
+
+  let extraClassDeclaration = [{
+    ObjectFifoCreateOp getObjectFifo();
+  }];
+}
+
+def AIE_ObjectFifoGetBufferOp : AIE_Op<"objectfifo.buffer", []> {
+  let summary = "Get a buffer reference from an ObjectFIFO without acquiring";
+  let description = [{
+    Returns a memref to the ObjectFIFO buffer at the given element index,
+    without performing any lock acquisition. This is intended for use with
+    precompiled C kernels that manage their own locking via
+    `aie.objectfifo.lock`.
+
+    Example:
+    ```
+      %buf = aie.objectfifo.buffer @of1 (0) : memref<256xi32>
+    ```
+    The returned memref can be passed to an external C function along with
+    lock IDs from `aie.objectfifo.lock`.
+  }];
+
+  let arguments = (
+    ins FlatSymbolRefAttr:$objFifo_name,
+        ConfinedAttr<AIEI32Attr, [IntMinValue<0>]>:$index
+  );
+
+  let results = (outs AnyMemRef:$output);
+
+  let assemblyFormat = [{
+    attr-dict $objFifo_name `(` $index `)` `:` qualified(type($output))
+  }];
+
+  let hasVerifier = 1;
+
+  let extraClassDeclaration = [{
+    ObjectFifoCreateOp getObjectFifo();
+  }];
+}
+
 def AIE_ObjectFifoRegisterProcessOp: AIE_Op<"objectfifo.register_process", []> {
   let summary = "Operation that produces the acquire/release patterns for a process registered to an objectFifo";
   let description = [{

lib/Dialect/AIE/IR/AIEDialect.cpp

@@ -1044,6 +1044,91 @@ LogicalResult ObjectFifoSubviewAccessOp::verify() {
   return success();
 }
 
+//===----------------------------------------------------------------------===//
+// ObjectFifoGetLockOp
+//===----------------------------------------------------------------------===//
+
+LogicalResult ObjectFifoGetLockOp::verify() {
+  auto parent = getOperation()->getParentOfType<CoreOp>();
+  if (parent == nullptr)
+    return emitOpError("must be called from inside a CoreOp");
+
+  auto coreTile = parent.getTile();
+  auto objFifo = getObjectFifo();
+  if (!objFifo)
+    return emitError("cannot retrieve associated object FIFO");
+  if (getPort() == ObjectFifoPort::Produce) {
+    if (coreTile != objFifo.getProducerTile())
+      return parent.emitOpError(
+          "producer port of objectFifo accessed by core running "
+          "on non-producer tile");
+  } else if (getPort() == ObjectFifoPort::Consume) {
+    bool found = false;
+    for (auto consumerTile : objFifo.getConsumerTiles()) {
+      if (coreTile == consumerTile) {
+        found = true;
+        break;
+      }
+    }
+    if (!found)
+      return parent.emitOpError(
+          "consumer port of objectFifo accessed by core running "
+          "on non-consumer tile");
+  }
+
+  return success();
+}
+
+ObjectFifoCreateOp ObjectFifoGetLockOp::getObjectFifo() {
+  Operation *parent = getOperation();
+  while ((parent = parent->getParentOp())) {
+    if (parent->hasTrait<OpTrait::SymbolTable>()) {
+      if (auto *st = SymbolTable::lookupSymbolIn(parent, getObjFifoName());
+          isa_and_nonnull<ObjectFifoCreateOp>(st))
+        return dyn_cast<ObjectFifoCreateOp>(st);
+    }
+  }
+  return {};
+}
+
+//===----------------------------------------------------------------------===//
+// ObjectFifoGetBufferOp
+//===----------------------------------------------------------------------===//
+
+LogicalResult ObjectFifoGetBufferOp::verify() {
+  auto parent = getOperation()->getParentOfType<CoreOp>();
+  if (parent == nullptr)
+    return emitOpError("must be called from inside a CoreOp");
+
+  auto objFifo = getObjectFifo();
+  if (!objFifo)
+    return emitError("cannot retrieve associated object FIFO");
+
+  auto objFifoElem =
+      llvm::cast<AIEObjectFifoType>(objFifo.getElemType()).getElementType();
+  if (objFifoElem != getOutput().getType())
+    return emitOpError("output memref type must match ObjectFifo element type");
+
+  int index = getIndex();
+  if (index >= objFifo.size())
+    return emitOpError("buffer index ")
+           << index << " exceeds ObjectFifo depth " << objFifo.size();
+
+  return success();
+}
+
+ObjectFifoCreateOp ObjectFifoGetBufferOp::getObjectFifo() {
+  Operation *parent = getOperation();
+  while ((parent = parent->getParentOp())) {
+    if (parent->hasTrait<OpTrait::SymbolTable>()) {
+      if (auto *st = SymbolTable::lookupSymbolIn(parent, getObjFifoName());
+          isa_and_nonnull<ObjectFifoCreateOp>(st))
+        return dyn_cast<ObjectFifoCreateOp>(st);
+    }
+  }
+  return {};
+}
+
 //===----------------------------------------------------------------------===//
 // ObjectFifoRegisterProcessOp
 //===----------------------------------------------------------------------===//

lib/Dialect/AIE/Transforms/AIELocalizeLocks.cpp

@@ -58,7 +58,7 @@ struct AIELocalizeLocksPass : AIELocalizeLocksBase<AIELocalizeLocksPass> {
             // it suffices to check if the parent of a UseLockOp is coreOp.
             if (llvm::none_of(lock.getResult().getUsers(),
                               [&](Operation *user) {
-                                return user->getParentOp() == coreOp;
+                                return coreOp->isProperAncestor(user);
                               }))
               continue;
 
@@ -77,7 +77,7 @@ struct AIELocalizeLocksPass : AIELocalizeLocksBase<AIELocalizeLocksPass> {
                 builder, builder.getUnknownLoc(), localLockIndex);
             lock.getResult().replaceUsesWithIf(
                 coreLockIDValue, [&](OpOperand &opOperand) {
-                  return opOperand.getOwner()->getParentOp() == coreOp;
+                  return coreOp->isProperAncestor(opOperand.getOwner());
                 });
           }
       }