Workspace Estimation Shared Header Agent Skill

Workspace-Estimation Shared Header: DLL-Boundary Pitfalls

Lessons from implementing the two-level (EstimateWorkspace / DeclareWorkspaceRequirements)

workspace-size estimation pilot for MatMulNBits (issue #29775 Phase-A, PR #29811). The

WorkspaceRequirement struct in include/onnxruntime/core/framework/workspace_requirement.h is

designed to be included by both in-tree kernel code and future plugin-EP adapter code — this is exactly

the kind of dual-included, DLL-boundary-crossing header where these gotchas apply.

1. Never forward-declare Node in a header included from both worlds

Symptom: a compile failure or, worse, a silent type mismatch that depends on include order —

because onnxruntime::Node is not one type across the whole codebase. In-tree code sees class Node

from core/graph/graph.h. Shared-provider/plugin-bridge code (anything reachable from a plugin DLL)

sees a *different* Node type from a provider-bridge header (e.g. struct Node final). These are two

distinct types that happen to share a name — different "ODR worlds."

The trap: writing class Node; (or any forward-declaration of Node) in a header that might be

#included from both worlds. Whichever world's real definition gets included later in the same

translation unit can clash with your forward-declaration's class-key (class vs struct), or — worse

— the header can compile fine in isolation and only fail (or silently pick the wrong type) once combined

with a specific set of other includes.

The fix: omit the forward-declaration entirely. Don't try to avoid the #include of the real Node

header for compile-time savings in a shared, dual-included header — let each translation unit's own

real includes provide whatever Node type it needs. If you only need a pointer/reference and think a

forward-declare is a safe optimization, it is not safe here specifically because the two worlds disagree

on the underlying type.

How to confirm you're clear: the header must build cleanly when included from an in-tree-only

translation unit AND (once such a target exists) from a plugin-DLL translation unit, without relying on

which one happens to be included first.

2. Keep the shared/reusable half of a workspace-estimation function free of graph types

When a kernel's workspace-size computation needs to be callable from both in-tree and (eventually)

plugin code, split it into two pieces:

• Pure-math core — takes only plain shape/arch integers (e.g.

ComputeFpAIntBGemmWorkspaceSize(int m, int n, int k, int sm, int multiProcessorCount)). No

Node&, no NodeArg, no TensorShape parsing, no ORT graph types at all. This is the part a future

plugin implementation can call *verbatim* — plugin kernels don't have Node& access, only the C-ABI

shape representation (OrtNode, Node_GetInputShape).

• Graph-parsing wrapper — extracts the plain integers from const Node&/NodeArg/TensorShape (or

from the plugin's C-ABI shape accessors). This half is inherently different per build configuration and

is NOT reusable across the DLL boundary; it must be reimplemented against whichever shape

representation the caller has.

Why this matters concretely: if you accidentally let the pure-math core accept or touch an in-tree

graph type (even just to read one field), you've made it impossible to reuse from the plugin path without

either (a) linking in-tree graph headers into the plugin DLL (defeats the purpose of a plugin boundary) or

(b) duplicating the whole function. Keep the split clean from the start.

How to confirm you're clear: grep the pure-math function's signature and body for any ORT graph type

(Node, NodeArg, TensorShape, GraphViewer, etc.) — it should only ever see plain scalars

(int/int64_t/size_t) and, at most, opaque device-property values already extracted by the caller.

If you find a graph type anywhere in that function, the split has leaked and needs to be pulled apart

before a plugin implementation can reuse it.

Related, not yet built: docs/annotated_partitioning/future_directions_constrained_env.md (Phase A /

plugin-ABI sections) describes the intended plugin-side C ABI surface for DeclareWorkspaceRequirements,

but as of PR #29811 no plugin-side implementation exists yet — see that doc's "Cost of a Real

Plugin-Side Override (Deferred)" note for what's still missing beyond just following this split.