[GPU] tensor from nthandle

docs/articles_en/assets/snippets/gpu/remote_objects_creation.cpp

@@ -1,3 +1,7 @@
+// Copyright (C) 2018-2026 Intel Corporation
+// SPDX-License-Identifier: Apache-2.0
+//
+
 #include <openvino/runtime/core.hpp>
 #include <openvino/runtime/intel_gpu/properties.hpp>
 #include <openvino/runtime/intel_gpu/ocl/ocl.hpp>
@@ -14,6 +18,7 @@ cl_context get_cl_context();
 cl_command_queue get_cl_queue();
 cl::Buffer allocate_buffer(size_t size);
 cl::Image2D allocate_image(size_t size);
+ov::intel_gpu::ocl::os_handle_param get_shared_handle();
 
 
 #ifdef WIN32
@@ -62,6 +67,16 @@ int main() {
     //! [wrap_cl_image]
 }
 
+{
+    //! [wrap_shared_handle]
+    auto shared_handle = get_shared_handle();
+    auto remote_tensor = gpu_context.create_tensor(in_element_type,
+                                                   in_shape,
+                                                   shared_handle,
+                                                   ov::intel_gpu::MemType::SHARED_BUF);
+    //! [wrap_shared_handle]
+}
+
 {
     //! [allocate_usm_device]
     auto remote_tensor = gpu_context.create_usm_device_tensor(in_element_type, in_shape);

docs/articles_en/openvino-workflow/running-inference/inference-devices-and-modes/gpu-device/remote-tensor-api-gpu-plugin.rst

@@ -254,6 +254,19 @@ For more details, see the code snippets below:
                :language: cpp
                :fragment: [wrap_cl_image]
 
+         .. tab-item:: external shared handle
+            :sync: external-shared-handle
+
+            Use this overload when your application already owns an OS-level shared memory handle
+            (for example, DX12 NT handle on Windows or DMA-BUF file descriptor on Linux).
+
+            .. doxygensnippet:: docs/articles_en/assets/snippets/gpu/remote_objects_creation.cpp
+               :language: cpp
+               :fragment: [wrap_shared_handle]
+
+            The ``shape`` and ``element type`` must describe the same memory layout as the external buffer.
+            The handle must remain valid for the whole lifetime of the created remote tensor.
+
          .. tab-item:: biplanar NV12 surface
             :sync: biplanar-nv12-surface
 

src/inference/include/openvino/runtime/intel_gpu/ocl/ocl.hpp

@@ -38,8 +38,19 @@ namespace ocl {
  * @brief Shortcut for defining a handle parameter
  * @ingroup ov_runtime_ocl_gpu_cpp_api
  */
+
 using gpu_handle_param = void*;
 
+/**
+ * @brief Shortcut for defining a HANDLE on windows or file descriptor on linux
+ * @ingroup ov_runtime_ocl_gpu_cpp_api
+ */
+#ifdef __linux__
+using os_handle_param = int;
+#else
+using os_handle_param = void*;
+#endif
+
 /**
  * @brief This class represents an abstraction for GPU plugin remote tensor
  * which can be shared with user-supplied OpenCL buffer.
@@ -58,6 +69,7 @@ class ClBufferTensor : public RemoteTensor {
                                  {{std::string(ov::intel_gpu::mem_handle.name()), {}},
                                   {std::string(ov::intel_gpu::shared_mem_type.name()),
                                    {ov::Any(ov::intel_gpu::SharedMemType::OCL_BUFFER).as<std::string>(),
+                                    ov::Any(ov::intel_gpu::SharedMemType::BUFFER_FROM_HANDLE).as<std::string>(),
                                     ov::Any(ov::intel_gpu::SharedMemType::DX_BUFFER).as<std::string>()}}});
     }
 
@@ -307,6 +319,30 @@ class ClContext : public RemoteContext {
         return create_tensor(type, shape, params).as<ClImage2DTensor>();
     }
 
+    /**
+     * @brief This function is used to obtain a remote tensor object from a user-supplied external memory handle
+     *        The API mirrors the NPU pointer-based create_tensor form.
+     * @param type Tensor element type
+     * @param shape Tensor shape
+     * @param shared_buffer External memory handle from another API (DX12 shared NT handle on Windows passed as void*,
+     *                     DMA-BUF fd on Linux passed as int)
+     * @param memory_type Memory type to use; only MemType::SHARED_BUF is currently supported
+     * @return A remote tensor instance
+     */
+    ClBufferTensor create_tensor(const element::Type type,
+                                 const Shape& shape,
+                                 os_handle_param shared_buffer,
+                                 const MemType memory_type) {
+#ifndef __linux__
+        OPENVINO_ASSERT(shared_buffer != nullptr, "shared_buffer must not be nullptr for SHARED_BUF memory type");
+#endif
+        OPENVINO_ASSERT(memory_type == MemType::SHARED_BUF,
+                        "Only SHARED_BUF memory type is supported for raw buffer pointer or NT handle");
+        AnyMap params = {{ov::intel_gpu::shared_mem_type.name(), ov::intel_gpu::SharedMemType::BUFFER_FROM_HANDLE},
+                         {ov::intel_gpu::mem_handle.name(), reinterpret_cast<void*>(shared_buffer)}};
+        return create_tensor(type, shape, params).as<ClBufferTensor>();
+    }
+
     /**
      * @brief This function is used to obtain remote tensor object from user-supplied USM pointer
      * @param type Tensor element type

src/inference/include/openvino/runtime/intel_gpu/remote_properties.hpp

@@ -103,13 +103,23 @@ static constexpr Property<gpu_handle_param> va_device{"VA_DEVICE"};
  * @ingroup ov_runtime_ocl_gpu_cpp_api
  */
 enum class SharedMemType {
-    OCL_BUFFER = 0,         //!< Shared OpenCL buffer blob
-    OCL_IMAGE2D = 1,        //!< Shared OpenCL 2D image blob
-    USM_USER_BUFFER = 2,    //!< Shared USM pointer allocated by user
-    USM_HOST_BUFFER = 3,    //!< Shared USM pointer type with host allocation type allocated by plugin
-    USM_DEVICE_BUFFER = 4,  //!< Shared USM pointer type with device allocation type allocated by plugin
-    VA_SURFACE = 5,         //!< Shared video decoder surface or D3D 2D texture blob
-    DX_BUFFER = 6           //!< Shared D3D buffer blob
+    OCL_BUFFER = 0,          //!< Shared OpenCL buffer blob
+    OCL_IMAGE2D = 1,         //!< Shared OpenCL 2D image blob
+    USM_USER_BUFFER = 2,     //!< Shared USM pointer allocated by user
+    USM_HOST_BUFFER = 3,     //!< Shared USM pointer type with host allocation type allocated by plugin
+    USM_DEVICE_BUFFER = 4,   //!< Shared USM pointer type with device allocation type allocated by plugin
+    VA_SURFACE = 5,          //!< Shared video decoder surface or D3D 2D texture blob
+    DX_BUFFER = 6,           //!< Shared D3D buffer blob
+    BUFFER_FROM_HANDLE = 7,  //!< OS-level external memory handle (e.g. DX12 NT handle on Windows,
+                             //!< DMA-BUF fd on Linux) imported by the plugin into a cl_mem
+};
+
+/**
+ * @brief Enum to define memory type for pointer-based tensor sharing API.
+ * @ingroup ov_runtime_ocl_gpu_cpp_api
+ */
+enum class MemType {
+    SHARED_BUF = 0,  //!< Shared OpenCL buffer handle passed as void*
 };
 
 /** @cond INTERNAL */
@@ -129,6 +139,8 @@ inline std::ostream& operator<<(std::ostream& os, const SharedMemType& share_mem
         return os << "VA_SURFACE";
     case SharedMemType::DX_BUFFER:
         return os << "DX_BUFFER";
+    case SharedMemType::BUFFER_FROM_HANDLE:
+        return os << "BUFFER_FROM_HANDLE";
     default:
         OPENVINO_THROW("Unsupported memory type");
     }
@@ -151,6 +163,8 @@ inline std::istream& operator>>(std::istream& is, SharedMemType& share_mem_type)
         share_mem_type = SharedMemType::VA_SURFACE;
     } else if (str == "DX_BUFFER") {
         share_mem_type = SharedMemType::DX_BUFFER;
+    } else if (str == "BUFFER_FROM_HANDLE") {
+        share_mem_type = SharedMemType::BUFFER_FROM_HANDLE;
     } else {
         OPENVINO_THROW("Unsupported memory type: ", str);
     }

src/plugins/intel_gpu/include/intel_gpu/plugin/common_utils.hpp

@@ -23,6 +23,7 @@ enum class TensorType {
     BT_EMPTY,
     BT_BUF_INTERNAL,
     BT_BUF_SHARED,
+    BT_BUF_SHARED_FROM_HANDLE,
     BT_USM_SHARED,
     BT_USM_HOST_INTERNAL,
     BT_USM_DEVICE_INTERNAL,

src/plugins/intel_gpu/include/intel_gpu/runtime/engine.hpp

@@ -67,6 +67,9 @@ class engine {
     /// Create shared memory object using user-supplied memory buffer @p buf using specified @p layout
     memory_ptr share_buffer(const layout& layout, shared_handle buf);
 
+    //Create memory object from user-supplied shared handle e.g from system HANDLE created by DX12
+    virtual memory_ptr import_buffer(const layout& layout, shared_handle external_handle) = 0;
+
     /// Create shared memory object using user-supplied USM pointer @p usm_ptr using specified @p layout
     memory_ptr share_usm(const layout& layout, shared_handle usm_ptr);
 

src/plugins/intel_gpu/src/plugin/remote_context.cpp

@@ -169,6 +169,9 @@ ov::SoPtr<ov::IRemoteTensor> RemoteContextImpl::create_tensor(const ov::element:
                 mem = extract_object(params, ov::intel_gpu::dev_object_handle);
                 check_if_shared();
 #endif
+            } else if (ov::intel_gpu::SharedMemType::BUFFER_FROM_HANDLE == mem_type) {
+                tensor_type = TensorType::BT_BUF_SHARED_FROM_HANDLE;
+                mem = extract_object(params, ov::intel_gpu::mem_handle);
             } else {
                 OPENVINO_THROW("[GPU] Unsupported shared object type ", mem_type);
             }

src/plugins/intel_gpu/src/plugin/remote_tensor.cpp

@@ -340,6 +340,10 @@ void RemoteTensorImpl::allocate() {
         m_memory_object = engine.share_buffer(m_layout, m_mem);
         break;
     }
+    case TensorType::BT_BUF_SHARED_FROM_HANDLE: {
+        m_memory_object = engine.import_buffer(m_layout, m_mem);
+        break;
+    }
     case TensorType::BT_USM_SHARED: {
         m_memory_object = engine.share_usm(m_layout, m_mem);
         break;
@@ -380,6 +384,7 @@ const std::string& RemoteTensorImpl::get_device_name() const {
 
 bool RemoteTensorImpl::is_shared() const noexcept {
     return m_mem_type == TensorType::BT_BUF_SHARED ||
+           m_mem_type == TensorType::BT_BUF_SHARED_FROM_HANDLE ||
            m_mem_type == TensorType::BT_USM_SHARED ||
            m_mem_type == TensorType::BT_IMG_SHARED ||
            m_mem_type == TensorType::BT_SURF_SHARED ||
@@ -451,6 +456,13 @@ void RemoteTensorImpl::update_properties() {
             ov::intel_gpu::mem_handle(params.mem),
         };
         break;
+    case TensorType::BT_BUF_SHARED_FROM_HANDLE:
+        m_properties = {
+            ov::intel_gpu::shared_mem_type(ov::intel_gpu::SharedMemType::BUFFER_FROM_HANDLE),
+            ov::intel_gpu::ocl_context(params.context),
+            ov::intel_gpu::mem_handle(params.mem),
+        };
+        break;
     case TensorType::BT_USM_SHARED:
         m_properties = {
             ov::intel_gpu::shared_mem_type(ov::intel_gpu::SharedMemType::USM_USER_BUFFER),

src/plugins/intel_gpu/src/runtime/ocl/ocl_engine.cpp

@@ -13,7 +13,6 @@
 #include <string>
 #include <vector>
 #include <memory>
-#include <set>
 #include <stdexcept>
 
 // NOTE: Due to buggy scope transition of warnings we need to disable warning in place of use/instantation
@@ -46,6 +45,16 @@ ocl_error::ocl_error(cl::Error const& err)
     : ov::Exception("[GPU] " + std::string(err.what()) + std::string(", error code: ") + std::to_string(err.err())) {}
 OPENVINO_SUPPRESS_DEPRECATED_END
 
+namespace {
+cl_platform_id get_platform_id_for_device(const cl::Device& device) {
+    cl_platform_id platform = nullptr;
+    cl_int err = clGetDeviceInfo(device.get(), CL_DEVICE_PLATFORM, sizeof(platform), &platform, nullptr);
+    OPENVINO_ASSERT(err == CL_SUCCESS && platform != nullptr,
+                    "[GPU] Failed to retrieve CL_DEVICE_PLATFORM, error: ", err);
+    return platform;
+}
+}  // namespace
+
 ocl_engine::ocl_engine(const device::ptr dev, runtime_types runtime_type)
     : engine(dev) {
     OPENVINO_ASSERT(runtime_type == runtime_types::ocl, "[GPU] Invalid runtime type specified for OCL engine. Only OCL runtime is supported");
@@ -96,6 +105,63 @@ allocation_type ocl_engine::detect_usm_allocation_type(const void* memory) const
                                        : allocation_type::unknown;
 }
 
+memory::ptr ocl_engine::import_buffer(const layout& layout, shared_handle external_handle) {
+    OPENVINO_ASSERT(external_handle != nullptr, "[GPU] External memory handle must not be null");
+    OPENVINO_ASSERT(extension_supported("cl_khr_external_memory"),
+                    "[GPU] Selected OpenCL device does not advertise cl_khr_external_memory; "
+                    "external memory import is not supported");
+
+#ifndef CL_VERSION_3_0
+    OPENVINO_THROW("[GPU] External memory import is not supported on this platform");
+#else
+#ifdef _WIN32
+    constexpr auto handle_type_token = CL_EXTERNAL_MEMORY_HANDLE_OPAQUE_WIN32_KHR;
+#elif defined(__linux__)
+    constexpr auto handle_type_token = CL_EXTERNAL_MEMORY_HANDLE_DMA_BUF_KHR;
+#else
+    OPENVINO_THROW("[GPU] External memory import is not supported on this platform");
+#endif
+
+    cl_mem_properties props[] = {
+        static_cast<cl_mem_properties>(handle_type_token),
+        static_cast<cl_mem_properties>(reinterpret_cast<intptr_t>(external_handle)),
+        0,
+    };
+
+    cl_int errcode = CL_SUCCESS;
+    auto cl_ctx = static_cast<cl_context>(get_user_context());
+    OPENVINO_ASSERT(cl_ctx != nullptr, "[GPU] OpenCL context is null while importing external buffer");
+    const auto byte_size = layout.bytes_count();
+    cl_mem imported = clCreateBufferWithProperties(cl_ctx, props, CL_MEM_READ_WRITE, byte_size, nullptr, &errcode);
+    OPENVINO_ASSERT(errcode == CL_SUCCESS && imported != nullptr,
+                    "[GPU] Failed to import external memory handle via clCreateBufferWithProperties, error: ",
+                    errcode);
+
+    cl_platform_id platform = get_platform_id_for_device(get_cl_device());
+    auto& svc_stream = downcast<ocl_stream>(get_service_stream());
+    cl_command_queue q = svc_stream.get_cl_queue().get();
+    cl_int acquire_err = cl::ExternalMemoryHelper::acquire(platform, q, imported);
+    if (acquire_err != CL_SUCCESS) {
+        clReleaseMemObject(imported);
+        OPENVINO_THROW("[GPU] clEnqueueAcquireExternalMemObjectsKHR failed or unavailable, error: ", acquire_err);
+    }
+    clFinish(q);
+    cl::Buffer buf(imported, true);
+    auto memory = std::make_shared<ocl::gpu_buffer_from_handle>(this, layout, buf, nullptr);
+    clReleaseMemObject(imported);
+    return memory;
+#endif
+}
+
+void ocl_engine::release_external_memory(cl_mem mem) const {
+    cl_platform_id platform = get_platform_id_for_device(get_cl_device());
+    auto& opencl_stream = downcast<ocl_stream>(get_service_stream());
+    cl_command_queue q = opencl_stream.get_cl_queue().get();
+    // If the extension entrypoint is missing, the cl_mem refcount drop on dtor will still proceed.
+    cl::ExternalMemoryHelper::release(platform, q, mem);
+    clFinish(q);
+}
+
 memory::ptr ocl_engine::allocate_memory(const layout& layout, allocation_type type, bool reset) {
     OPENVINO_ASSERT(!layout.is_dynamic() || layout.has_upper_bound(), "[GPU] Can't allocate memory for dynamic layout");
 

src/plugins/intel_gpu/src/runtime/ocl/ocl_engine.hpp

@@ -10,8 +10,6 @@
 #include "ocl_device.hpp"
 
 #include <memory>
-#include <set>
-#include <vector>
 #include <utility>
 #include <string>
 
@@ -28,8 +26,11 @@ class ocl_engine : public engine {
     memory_ptr reinterpret_handle(const layout& new_layout, shared_mem_params params) override;
     memory_ptr create_subbuffer(const memory& memory, const layout& new_layout, size_t offset) override;
     memory_ptr reinterpret_buffer(const memory& memory, const layout& new_layout) override;
+    memory_ptr import_buffer(const layout&, shared_handle external_handle) override;
     bool is_the_same_buffer(const memory& mem1, const memory& mem2) override;
 
+    void release_external_memory(cl_mem) const;
+
     void* get_user_context() const override;
 
     allocation_type get_default_allocation_type() const override { return allocation_type::cl_mem; }

src/plugins/intel_gpu/src/runtime/ocl/ocl_ext.hpp

@@ -693,6 +693,56 @@ class BufferDX : public Buffer {
 };
 #endif
 
+class ExternalMemoryHelper {
+    typedef CL_API_ENTRY cl_int(CL_API_CALL * PFN_clEnqueueAcquireExternalMemObjectsKHR)(
+        cl_command_queue /* command_queue */,
+        cl_uint /* num_mem_objects */,
+        const cl_mem* /* mem_objects */,
+        cl_uint /* num_events_in_wait_list */,
+        const cl_event* /* event_wait_list */,
+        cl_event* /* event */);
+
+    typedef CL_API_ENTRY cl_int(CL_API_CALL * PFN_clEnqueueReleaseExternalMemObjectsKHR)(
+        cl_command_queue /* command_queue */,
+        cl_uint /* num_mem_objects */,
+        const cl_mem* /* mem_objects */,
+        cl_uint /* num_events_in_wait_list */,
+        const cl_event* /* event_wait_list */,
+        cl_event* /* event */);
+public:
+
+    static cl_int acquire(cl_platform_id platform, cl_command_queue queue, const cl_mem& mem) {
+        auto pfn = get_acquire(platform);
+        if (pfn == nullptr)
+            return CL_INVALID_OPERATION;
+        return pfn(queue, 1, &mem, 0, nullptr, nullptr);
+    }
+
+    static cl_int release(cl_platform_id platform, cl_command_queue queue, const cl_mem& mem) {
+        auto pfn = get_release(platform);
+        if (pfn == nullptr)
+            return CL_INVALID_OPERATION;
+        return pfn(queue, 1, &mem, 0, nullptr, nullptr);
+    }
+private:
+    static PFN_clEnqueueAcquireExternalMemObjectsKHR get_acquire(cl_platform_id platform) {
+        static PFN_clEnqueueAcquireExternalMemObjectsKHR fn = nullptr;
+        if (!fn) {
+            fn = try_load_entrypoint<PFN_clEnqueueAcquireExternalMemObjectsKHR>(platform, "clEnqueueAcquireExternalMemObjectsKHR");
+        }
+        return fn;
+    }
+
+    static PFN_clEnqueueReleaseExternalMemObjectsKHR get_release(cl_platform_id platform) {
+        static PFN_clEnqueueReleaseExternalMemObjectsKHR fn = nullptr;
+        if (!fn) {
+            fn = try_load_entrypoint<PFN_clEnqueueReleaseExternalMemObjectsKHR>(platform, "clEnqueueReleaseExternalMemObjectsKHR");
+        }
+        return fn;
+    }
+
+};
+
 class PlatformVA : public Platform {
 public:
     //! \brief Default constructor - initializes to NULL.