From d1e9a070165bd85536fe4e17c7ddf336226d8a0e Mon Sep 17 00:00:00 2001 From: Shuli Shu <08cnbj@gmail.com> Date: Tue, 8 Sep 2026 15:20:21 -0400 Subject: [PATCH 01/15] init commit --- doc/code/dialects/Executor/ExecutorDialect.md | 9 +- .../dialects/Transport/TransportAttributes.md | 63 +++++++++ .../dialects/Transport/TransportDialect.md | 130 ++---------------- doc/code/dialects/Transport/TransportTypes.md | 25 ++++ doc/code/dialects/executor.rst | 5 + doc/code/dialects/transport.rst | 15 ++ mlir/include/Executor/IR/ExecutorDialect.td | 9 ++ mlir/include/Transport/IR/CMakeLists.txt | 2 + .../include/Transport/IR/TransportAttrDefs.td | 87 ++++++++++++ mlir/include/Transport/IR/TransportDialect.td | 127 +++-------------- mlir/include/Transport/IR/TransportOps.td | 2 + mlir/include/Transport/IR/TransportTypes.td | 60 ++++++++ 12 files changed, 312 insertions(+), 222 deletions(-) create mode 100644 doc/code/dialects/Transport/TransportAttributes.md create mode 100644 doc/code/dialects/Transport/TransportTypes.md create mode 100644 mlir/include/Transport/IR/TransportAttrDefs.td create mode 100644 mlir/include/Transport/IR/TransportTypes.td diff --git a/doc/code/dialects/Executor/ExecutorDialect.md b/doc/code/dialects/Executor/ExecutorDialect.md index 6dd91fdb94..ae4df47f9d 100644 --- a/doc/code/dialects/Executor/ExecutorDialect.md +++ b/doc/code/dialects/Executor/ExecutorDialect.md @@ -12,4 +12,11 @@ interacts with an executor service: * Dispatching a previously-shipped qnode kernel * Invoking an arbitrary symbol in a shared library -[TOC] +`dispatch-executor-targets` is what emits these ops. One caller is the `transport` dialect's +bring-up: a [PennyLane](https://docs.pennylane.ai/en/stable/) `Placement` node marked as +running out of process needs its code on the machine that runs it, which is what this dialect +describes. + +> [!IMPORTANT] +> The executor dialect is experimental and will not maintain API stability between +> releases. Use at your own risk. diff --git a/doc/code/dialects/Transport/TransportAttributes.md b/doc/code/dialects/Transport/TransportAttributes.md new file mode 100644 index 0000000000..87dcc368b9 --- /dev/null +++ b/doc/code/dialects/Transport/TransportAttributes.md @@ -0,0 +1,63 @@ + + +### BacklineAttr + +_A backline placement: one controller and the coprocessors it drives._ + +Syntax: + +``` +#transport.backline< + mlir::StringAttr, # transport + ::catalyst::transport::NodeAttr, # controller + ::llvm::ArrayRef<::catalyst::transport::NodeAttr> # coprocessors +> +``` + +#### Parameters: + +| Parameter | C++ type | Description | +| :-------: | :-------: | ----------- | +| transport | `mlir::StringAttr` | transport carrying the traffic, selecting the compiled backend | +| controller | `::catalyst::transport::NodeAttr` | the controller node that drives the session | +| coprocessors | `::llvm::ArrayRef<::catalyst::transport::NodeAttr>` | the coprocessor nodes the controller drives | + +### NodeAttr + +_A backline participant: a controller or a coprocessor._ + +Syntax: + +``` +#transport.node< + mlir::StringAttr, # name + mlir::StringAttr, # peer + mlir::IntegerAttr, # oob_port + mlir::StringAttr, # backend_lib + mlir::StringAttr, # config + mlir::StringAttr, # triple + mlir::StringAttr, # address + mlir::StringAttr, # symbol + mlir::BoolAttr, # out_of_process + mlir::IntegerAttr, # in_bytes + mlir::IntegerAttr, # out_bytes + mlir::IntegerAttr # work_item_idx +> +``` + +#### Parameters: + +| Parameter | C++ type | Description | +| :-------: | :-------: | ----------- | +| name | `mlir::StringAttr` | this node's name; the session registry key when non-empty | +| peer | `mlir::StringAttr` | the peer's address for the out-of-band handshake | +| oob_port | `mlir::IntegerAttr` | TCP port for the out-of-band handshake | +| backend_lib | `mlir::StringAttr` | backend plugin the runtime dlopens for this node | +| config | `mlir::StringAttr` | backend configuration string, passed through verbatim | +| triple | `mlir::StringAttr` | target triple this node's code is compiled for | +| address | `mlir::StringAttr` | executor address when this node runs out of process | +| symbol | `mlir::StringAttr` | coprocessor function symbol the backend binds | +| out_of_process | `mlir::BoolAttr` | whether this node's code is dispatched to an executor rather than run in the compiling process | +| in_bytes | `mlir::IntegerAttr` | request size in bytes for one round | +| out_bytes | `mlir::IntegerAttr` | reply size in bytes for one round | +| work_item_idx | `mlir::IntegerAttr` | index of this node's work item within the round | diff --git a/doc/code/dialects/Transport/TransportDialect.md b/doc/code/dialects/Transport/TransportDialect.md index de28530489..591bc69c86 100644 --- a/doc/code/dialects/Transport/TransportDialect.md +++ b/doc/code/dialects/Transport/TransportDialect.md @@ -9,118 +9,18 @@ between two endpoints: creating a session, bringing up the connection, exchanging memory handles, establishing a data path, and running rounds of request/reply traffic until teardown. -This is what a Backline compiles to. A PennyLane `Placement` is serialized -into the `catalyst.backline` module attribute, naming one controller and the -coprocessors it drives; `inject-transport-session` reads that attribute and -emits the session bring-up and teardown in terms of these ops, -`lower-decode-to-transport` turns a decode into a request/reply round over -the session, and `convert-transport-to-llvm` lowers the result to -`__catalyst__transport__*` runtime calls. A node here is a Backline -participant -- a controller or a coprocessor -- and the placement's -transport selects which compiled backend carries the traffic. - -[TOC] - -## Attributes - -### BacklineAttr - -_A backline placement: one controller and the coprocessors it drives._ - -Syntax: - -``` -#transport.backline< - mlir::StringAttr, # transport - ::catalyst::transport::NodeAttr, # controller - ::llvm::ArrayRef<::catalyst::transport::NodeAttr> # coprocessors -> -``` - -#### Parameters: - -| Parameter | C++ type | Description | -| :-------: | :-------: | ----------- | -| transport | `mlir::StringAttr` | transport carrying the traffic, selecting the compiled backend | -| controller | `::catalyst::transport::NodeAttr` | the controller node that drives the session | -| coprocessors | `::llvm::ArrayRef<::catalyst::transport::NodeAttr>` | the coprocessor nodes the controller drives | - -### NodeAttr - -_A backline participant: a controller or a coprocessor._ - -Syntax: - -``` -#transport.node< - mlir::StringAttr, # name - mlir::StringAttr, # peer - mlir::IntegerAttr, # oob_port - mlir::StringAttr, # backend_lib - mlir::StringAttr, # config - mlir::StringAttr, # triple - mlir::StringAttr, # address - mlir::StringAttr, # symbol - mlir::BoolAttr, # out_of_process - mlir::IntegerAttr, # in_bytes - mlir::IntegerAttr, # out_bytes - mlir::IntegerAttr # work_item_idx -> -``` - -#### Parameters: - -| Parameter | C++ type | Description | -| :-------: | :-------: | ----------- | -| name | `mlir::StringAttr` | this node's name; the session registry key when non-empty | -| peer | `mlir::StringAttr` | the peer's address for the out-of-band handshake | -| oob_port | `mlir::IntegerAttr` | TCP port for the out-of-band handshake | -| backend_lib | `mlir::StringAttr` | backend plugin the runtime dlopens for this node | -| config | `mlir::StringAttr` | backend configuration string, passed through verbatim | -| triple | `mlir::StringAttr` | target triple this node's code is compiled for | -| address | `mlir::StringAttr` | executor address when this node runs out of process | -| symbol | `mlir::StringAttr` | coprocessor function symbol the backend binds | -| out_of_process | `mlir::BoolAttr` | whether this node's code is dispatched to an executor rather than run in the compiling process | -| in_bytes | `mlir::IntegerAttr` | request size in bytes for one round | -| out_bytes | `mlir::IntegerAttr` | reply size in bytes for one round | -| work_item_idx | `mlir::IntegerAttr` | index of this node's work item within the round | - -## Types - -### SessionType - -_An opaque transport session handle, tagged with its role._ - -Syntax: - -``` -!transport.session< - ::catalyst::transport::Role # role -> -``` - -#### Parameters: - -| Parameter | C++ type | Description | -| :-------: | :-------: | ----------- | -| role | `::catalyst::transport::Role` | an enum of type Role | - -### TokenType - -_A handle to an in-flight asynchronous step, awaited with transport.await._ - -Syntax: `!transport.token` - - -## Enums - -### Role - -_Transport session role_ - -#### Cases: - -| Symbol | Value | String | -| :----: | :---: | ------ | -| Controller | `0` | controller | -| Coprocessor | `1` | coprocessor | +This is what a Backline compiles to. A [PennyLane](https://docs.pennylane.ai/en/stable/) +`Placement` is serialized into the `catalyst.backline` module attribute, naming one +controller and the coprocessors it drives; `inject-transport-session` reads that attribute +and emits the session bring-up and teardown in terms of these ops, +`lower-decode-to-transport` turns a decode into a request/reply round over the session, and +`convert-transport-to-llvm` lowers the result to `__catalyst__transport__*` runtime calls. +A node here is a Backline participant -- a controller or a coprocessor -- and the +placement's transport selects which compiled backend carries the traffic. + +A node the placement dispatches to another machine is shipped and launched through the +`executor` dialect, so a placement that mixes local and dispatched nodes uses both. + +> [!IMPORTANT] +> The transport dialect is experimental and will not maintain API stability between +> releases. Use at your own risk. diff --git a/doc/code/dialects/Transport/TransportTypes.md b/doc/code/dialects/Transport/TransportTypes.md new file mode 100644 index 0000000000..7af6a15b2e --- /dev/null +++ b/doc/code/dialects/Transport/TransportTypes.md @@ -0,0 +1,25 @@ + + +### SessionType + +_An opaque transport session handle, tagged with its role._ + +Syntax: + +``` +!transport.session< + ::catalyst::transport::Role # role +> +``` + +#### Parameters: + +| Parameter | C++ type | Description | +| :-------: | :-------: | ----------- | +| role | `::catalyst::transport::Role` | an enum of type Role | + +### TokenType + +_A handle to an in-flight asynchronous step, awaited with transport.await._ + +Syntax: `!transport.token` diff --git a/doc/code/dialects/executor.rst b/doc/code/dialects/executor.rst index f23b98e2f2..d47d34ca3f 100644 --- a/doc/code/dialects/executor.rst +++ b/doc/code/dialects/executor.rst @@ -1,4 +1,9 @@ .. mdinclude:: Executor/ExecutorDialect.md + :end-line: -3 + +.. important:: + The executor dialect is experimental and will not maintain API stability between + releases. Use at your own risk. Types ----- diff --git a/doc/code/dialects/transport.rst b/doc/code/dialects/transport.rst index 3f51287d52..cb924dd870 100644 --- a/doc/code/dialects/transport.rst +++ b/doc/code/dialects/transport.rst @@ -1,5 +1,20 @@ .. mdinclude:: Transport/TransportDialect.md + :end-line: -3 +.. important:: + The transport dialect is experimental and will not maintain API stability between + releases. Use at your own risk. + + +Types +----- + +.. mdinclude:: Transport/TransportTypes.md + +Attributes +---------- + +.. mdinclude:: Transport/TransportAttributes.md Operations ---------- diff --git a/mlir/include/Executor/IR/ExecutorDialect.td b/mlir/include/Executor/IR/ExecutorDialect.td index 81ade9a398..bd779a2d2b 100644 --- a/mlir/include/Executor/IR/ExecutorDialect.td +++ b/mlir/include/Executor/IR/ExecutorDialect.td @@ -32,6 +32,15 @@ def Executor_Dialect : Dialect { * Shipping a cross-compiled kernel object file (or other assets) to that endpoint * Dispatching a previously-shipped qnode kernel * Invoking an arbitrary symbol in a shared library + + `dispatch-executor-targets` is what emits these ops. One caller is the `transport` dialect's + bring-up: a [PennyLane](https://docs.pennylane.ai/en/stable/) `Placement` node marked as + running out of process needs its code on the machine that runs it, which is what this dialect + describes. + + > [!IMPORTANT] + > The executor dialect is experimental and will not maintain API stability between + > releases. Use at your own risk. }]; let name = "executor"; diff --git a/mlir/include/Transport/IR/CMakeLists.txt b/mlir/include/Transport/IR/CMakeLists.txt index f898b85a9e..d430cc7578 100644 --- a/mlir/include/Transport/IR/CMakeLists.txt +++ b/mlir/include/Transport/IR/CMakeLists.txt @@ -1,5 +1,7 @@ add_mlir_dialect(TransportOps transport) add_mlir_doc(TransportDialect TransportDialect Transport/ -gen-dialect-doc) +add_mlir_doc(TransportTypes TransportTypes Transport/ -gen-typedef-doc) +add_mlir_doc(TransportAttrDefs TransportAttributes Transport/ -gen-attrdef-doc) add_mlir_doc(TransportOps TransportOps Transport/ -gen-op-doc) set(LLVM_TARGET_DEFINITIONS TransportOps.td) diff --git a/mlir/include/Transport/IR/TransportAttrDefs.td b/mlir/include/Transport/IR/TransportAttrDefs.td new file mode 100644 index 0000000000..82f9b6bf89 --- /dev/null +++ b/mlir/include/Transport/IR/TransportAttrDefs.td @@ -0,0 +1,87 @@ +// Copyright 2026 Xanadu Quantum Technologies Inc. + +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at + +// http://www.apache.org/licenses/LICENSE-2.0 + +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +#ifndef TRANSPORT_ATTRDEFS +#define TRANSPORT_ATTRDEFS + +include "mlir/IR/AttrTypeBase.td" + +include "Transport/IR/TransportDialect.td" + +//===----------------------------------------------------------------------===// +// Attributes. +//===----------------------------------------------------------------------===// + +// A string field that reads as empty when omitted, so consumers need no null checks. +class Transport_StrField : DefaultValuedParameter<"mlir::StringAttr", + "mlir::StringAttr::get($_ctxt, \"\")", desc>; + +def Transport_NodeAttr : Transport_Attr<"Node", "node"> { + let summary = "A backline participant: a controller or a coprocessor."; + + let parameters = (ins + Transport_StrField<"this node's name; the session registry key when non-empty">:$name, + Transport_StrField<"the peer's address for the out-of-band handshake">:$peer, + OptionalParameter<"mlir::IntegerAttr", + "TCP port for the out-of-band handshake">:$oob_port, + Transport_StrField<"backend plugin the runtime dlopens for this node">:$backend_lib, + Transport_StrField<"backend configuration string, passed through verbatim">:$config, + Transport_StrField<"target triple this node's code is compiled for">:$triple, + Transport_StrField<"executor address when this node runs out of process">:$address, + Transport_StrField<"coprocessor function symbol the backend binds">:$symbol, + OptionalParameter<"mlir::BoolAttr", + "whether this node's code is dispatched to an executor rather than " + "run in the compiling process">:$out_of_process, + OptionalParameter<"mlir::IntegerAttr", "request size in bytes for one round">:$in_bytes, + OptionalParameter<"mlir::IntegerAttr", "reply size in bytes for one round">:$out_bytes, + OptionalParameter<"mlir::IntegerAttr", + "index of this node's work item within the round">:$work_item_idx + ); + + let assemblyFormat = "`<` struct(params) `>`"; + + let extraClassDeclaration = [{ + /// Session registry key: `name` when set and non-empty, else `fallback`. + mlir::StringAttr keyOr(llvm::StringRef fallback) const; + + /// Whether this node's code is dispatched to an executor rather than run in the + /// compiling process. + bool isOutOfProcess() const; + + /// Integer field accessors. + int64_t oobPort() const; + int64_t inBytes() const; + int64_t outBytes() const; + int64_t workItemIdx() const; + }]; +} + +def Transport_BacklineAttr : Transport_Attr<"Backline", "backline"> { + let summary = "A backline placement: one controller and the coprocessors it drives."; + + let parameters = (ins + AttrParameter<"mlir::StringAttr", + "transport carrying the traffic, selecting the compiled backend">:$transport, + AttrParameter<"::catalyst::transport::NodeAttr", + "the controller node that drives the session">:$controller, + OptionalArrayRefParameter<"::catalyst::transport::NodeAttr", + "the coprocessor nodes the controller drives">:$coprocessors + ); + + let assemblyFormat = [{ `<` `transport` `=` $transport `,` `controller` `=` $controller + (`,` `coprocessors` `=` `[` $coprocessors^ `]`)? `>` }]; + let genVerifyDecl = 1; +} + +#endif // TRANSPORT_ATTRDEFS diff --git a/mlir/include/Transport/IR/TransportDialect.td b/mlir/include/Transport/IR/TransportDialect.td index 2ba0c970c4..4e85c380e2 100644 --- a/mlir/include/Transport/IR/TransportDialect.td +++ b/mlir/include/Transport/IR/TransportDialect.td @@ -33,9 +33,21 @@ def Transport_Dialect : Dialect { exchanging memory handles, establishing a data path, and running rounds of request/reply traffic until teardown. - A session's endpoints are a controller and a coprocessor, described by the - `#transport.backline` attribute a module carries as `catalyst.backline`. - Every op here lowers to a `__catalyst__transport__*` runtime call. + This is what a Backline compiles to. A [PennyLane](https://docs.pennylane.ai/en/stable/) + `Placement` is serialized into the `catalyst.backline` module attribute, naming one + controller and the coprocessors it drives; `inject-transport-session` reads that attribute + and emits the session bring-up and teardown in terms of these ops, + `lower-decode-to-transport` turns a decode into a request/reply round over the session, and + `convert-transport-to-llvm` lowers the result to `__catalyst__transport__*` runtime calls. + A node here is a Backline participant -- a controller or a coprocessor -- and the + placement's transport selects which compiled backend carries the traffic. + + A node the placement dispatches to another machine is shipped and launched through the + `executor` dialect, so a placement that mixes local and dispatched nodes uses both. + + > [!IMPORTANT] + > The transport dialect is experimental and will not maintain API stability between + > releases. Use at your own risk. }]; let name = "transport"; @@ -46,121 +58,24 @@ def Transport_Dialect : Dialect { } //===----------------------------------------------------------------------===// -// Enums. -//===----------------------------------------------------------------------===// - -def Transport_Role : I32EnumAttr<"Role", "transport session role", [ - I32EnumAttrCase<"Controller", 0, "controller">, - I32EnumAttrCase<"Coprocessor", 1, "coprocessor"> - ]> { - let cppNamespace = "::catalyst::transport"; -} - - -//===----------------------------------------------------------------------===// -// Types. +// Type and attribute base classes. //===----------------------------------------------------------------------===// +// +// Kept here so TransportTypes.td and TransportAttrDefs.td share them. The defs themselves live in +// those files rather than here: `-gen-dialect-doc` documents whatever attributes, types and enums +// it can reach, and this file is its entry point, so anything left here lands in +// TransportDialect.md ahead of the Types and Attributes sections instead of inside them. class Transport_Type traits = []> : TypeDef { let mnemonic = typeMnemonic; } -// Opaque session handle, parameterized by its role. The role is a compile-time tag -// that selects which role-specific ops the session may take part in. -def Transport_SessionType : Transport_Type<"Session", "session"> { - let summary = "An opaque transport session handle, tagged with its role."; - let parameters = (ins EnumParameter:$role); - let assemblyFormat = "`<` $role `>`"; -} - -def Transport_TokenType : Transport_Type<"Token", "token"> { - let summary = "A handle to an in-flight asynchronous step, awaited with transport.await."; -} - -// Role-constrained session types used by the role-specific ops. -def Transport_ControllerSession : Type< - CPred<"::llvm::isa<::catalyst::transport::SessionType>($_self) && " - "::llvm::cast<::catalyst::transport::SessionType>($_self).getRole() == " - "::catalyst::transport::Role::Controller">, - "controller transport session">; - -def Transport_CoprocessorSession : Type< - CPred<"::llvm::isa<::catalyst::transport::SessionType>($_self) && " - "::llvm::cast<::catalyst::transport::SessionType>($_self).getRole() == " - "::catalyst::transport::Role::Coprocessor">, - "coprocessor transport session">; - -//===----------------------------------------------------------------------===// -// Attributes. -//===----------------------------------------------------------------------===// - class Transport_Attr traits = []> : AttrDef { let mnemonic = attrMnemonic; } -// A string field that reads as empty when omitted, so consumers need no null checks. -class Transport_StrField : DefaultValuedParameter<"mlir::StringAttr", - "mlir::StringAttr::get($_ctxt, \"\")", desc>; - -def Transport_NodeAttr : Transport_Attr<"Node", "node"> { - let summary = "A backline participant: a controller or a coprocessor."; - - let parameters = (ins - Transport_StrField<"this node's name; the session registry key when non-empty">:$name, - Transport_StrField<"the peer's address for the out-of-band handshake">:$peer, - OptionalParameter<"mlir::IntegerAttr", - "TCP port for the out-of-band handshake">:$oob_port, - Transport_StrField<"backend plugin the runtime dlopens for this node">:$backend_lib, - Transport_StrField<"backend configuration string, passed through verbatim">:$config, - Transport_StrField<"target triple this node's code is compiled for">:$triple, - Transport_StrField<"executor address when this node runs out of process">:$address, - Transport_StrField<"coprocessor function symbol the backend binds">:$symbol, - OptionalParameter<"mlir::BoolAttr", - "whether this node's code is dispatched to an executor rather than " - "run in the compiling process">:$out_of_process, - OptionalParameter<"mlir::IntegerAttr", "request size in bytes for one round">:$in_bytes, - OptionalParameter<"mlir::IntegerAttr", "reply size in bytes for one round">:$out_bytes, - OptionalParameter<"mlir::IntegerAttr", - "index of this node's work item within the round">:$work_item_idx - ); - - let assemblyFormat = "`<` struct(params) `>`"; - - let extraClassDeclaration = [{ - /// Session registry key: `name` when set and non-empty, else `fallback`. - mlir::StringAttr keyOr(llvm::StringRef fallback) const; - - /// Whether this node's code is dispatched to an executor rather than run in the - /// compiling process. - bool isOutOfProcess() const; - - /// Integer field accessors. - int64_t oobPort() const; - int64_t inBytes() const; - int64_t outBytes() const; - int64_t workItemIdx() const; - }]; -} - -def Transport_BacklineAttr : Transport_Attr<"Backline", "backline"> { - let summary = "A backline placement: one controller and the coprocessors it drives."; - - let parameters = (ins - AttrParameter<"mlir::StringAttr", - "transport carrying the traffic, selecting the compiled backend">:$transport, - AttrParameter<"::catalyst::transport::NodeAttr", - "the controller node that drives the session">:$controller, - OptionalArrayRefParameter<"::catalyst::transport::NodeAttr", - "the coprocessor nodes the controller drives">:$coprocessors - ); - - let assemblyFormat = [{ `<` `transport` `=` $transport `,` `controller` `=` $controller - (`,` `coprocessors` `=` `[` $coprocessors^ `]`)? `>` }]; - let genVerifyDecl = 1; -} - //===----------------------------------------------------------------------===// // Operation base. //===----------------------------------------------------------------------===// diff --git a/mlir/include/Transport/IR/TransportOps.td b/mlir/include/Transport/IR/TransportOps.td index 66ecf5289b..7b074ebbad 100644 --- a/mlir/include/Transport/IR/TransportOps.td +++ b/mlir/include/Transport/IR/TransportOps.td @@ -19,7 +19,9 @@ include "mlir/IR/OpBase.td" include "mlir/IR/BuiltinAttributes.td" include "mlir/IR/CommonTypeConstraints.td" include "mlir/Interfaces/SideEffectInterfaces.td" +include "Transport/IR/TransportAttrDefs.td" include "Transport/IR/TransportDialect.td" +include "Transport/IR/TransportTypes.td" // A round's payload or reply buffer: a 1-D memref (buffer form) or tensor (value form). def Transport_Buffer : MemRefRankOf<[I1, I8, I16, I32, I64, Index], [1]>; diff --git a/mlir/include/Transport/IR/TransportTypes.td b/mlir/include/Transport/IR/TransportTypes.td new file mode 100644 index 0000000000..93617fa1df --- /dev/null +++ b/mlir/include/Transport/IR/TransportTypes.td @@ -0,0 +1,60 @@ +// Copyright 2026 Xanadu Quantum Technologies Inc. + +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at + +// http://www.apache.org/licenses/LICENSE-2.0 + +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +#ifndef TRANSPORT_TYPES +#define TRANSPORT_TYPES + +include "mlir/IR/AttrTypeBase.td" +include "mlir/IR/EnumAttr.td" + +include "Transport/IR/TransportDialect.td" + +//===----------------------------------------------------------------------===// +// Enums. +//===----------------------------------------------------------------------===// + +def Transport_Role : I32EnumAttr<"Role", "transport session role", [ + I32EnumAttrCase<"Controller", 0, "controller">, + I32EnumAttrCase<"Coprocessor", 1, "coprocessor"> + ]> { + let cppNamespace = "::catalyst::transport"; +} + + +// Opaque session handle, parameterized by its role. The role is a compile-time tag +// that selects which role-specific ops the session may take part in. +def Transport_SessionType : Transport_Type<"Session", "session"> { + let summary = "An opaque transport session handle, tagged with its role."; + let parameters = (ins EnumParameter:$role); + let assemblyFormat = "`<` $role `>`"; +} + +def Transport_TokenType : Transport_Type<"Token", "token"> { + let summary = "A handle to an in-flight asynchronous step, awaited with transport.await."; +} + +// Role-constrained session types used by the role-specific ops. +def Transport_ControllerSession : Type< + CPred<"::llvm::isa<::catalyst::transport::SessionType>($_self) && " + "::llvm::cast<::catalyst::transport::SessionType>($_self).getRole() == " + "::catalyst::transport::Role::Controller">, + "controller transport session">; + +def Transport_CoprocessorSession : Type< + CPred<"::llvm::isa<::catalyst::transport::SessionType>($_self) && " + "::llvm::cast<::catalyst::transport::SessionType>($_self).getRole() == " + "::catalyst::transport::Role::Coprocessor">, + "coprocessor transport session">; + +#endif // TRANSPORT_TYPES From 163c36787807379661e2d7b191821c59293aa1f7 Mon Sep 17 00:00:00 2001 From: Shuli Shu <08cnbj@gmail.com> Date: Tue, 8 Sep 2026 15:39:04 -0400 Subject: [PATCH 02/15] revert changes in mlir path only keep the changes made to transport dialect docs --- mlir/include/Executor/IR/ExecutorDialect.td | 9 -- mlir/include/Transport/IR/CMakeLists.txt | 2 - .../include/Transport/IR/TransportAttrDefs.td | 87 ------------ mlir/include/Transport/IR/TransportDialect.td | 127 +++++++++++++++--- mlir/include/Transport/IR/TransportOps.td | 2 - mlir/include/Transport/IR/TransportTypes.td | 60 --------- 6 files changed, 106 insertions(+), 181 deletions(-) delete mode 100644 mlir/include/Transport/IR/TransportAttrDefs.td delete mode 100644 mlir/include/Transport/IR/TransportTypes.td diff --git a/mlir/include/Executor/IR/ExecutorDialect.td b/mlir/include/Executor/IR/ExecutorDialect.td index bd779a2d2b..81ade9a398 100644 --- a/mlir/include/Executor/IR/ExecutorDialect.td +++ b/mlir/include/Executor/IR/ExecutorDialect.td @@ -32,15 +32,6 @@ def Executor_Dialect : Dialect { * Shipping a cross-compiled kernel object file (or other assets) to that endpoint * Dispatching a previously-shipped qnode kernel * Invoking an arbitrary symbol in a shared library - - `dispatch-executor-targets` is what emits these ops. One caller is the `transport` dialect's - bring-up: a [PennyLane](https://docs.pennylane.ai/en/stable/) `Placement` node marked as - running out of process needs its code on the machine that runs it, which is what this dialect - describes. - - > [!IMPORTANT] - > The executor dialect is experimental and will not maintain API stability between - > releases. Use at your own risk. }]; let name = "executor"; diff --git a/mlir/include/Transport/IR/CMakeLists.txt b/mlir/include/Transport/IR/CMakeLists.txt index d430cc7578..f898b85a9e 100644 --- a/mlir/include/Transport/IR/CMakeLists.txt +++ b/mlir/include/Transport/IR/CMakeLists.txt @@ -1,7 +1,5 @@ add_mlir_dialect(TransportOps transport) add_mlir_doc(TransportDialect TransportDialect Transport/ -gen-dialect-doc) -add_mlir_doc(TransportTypes TransportTypes Transport/ -gen-typedef-doc) -add_mlir_doc(TransportAttrDefs TransportAttributes Transport/ -gen-attrdef-doc) add_mlir_doc(TransportOps TransportOps Transport/ -gen-op-doc) set(LLVM_TARGET_DEFINITIONS TransportOps.td) diff --git a/mlir/include/Transport/IR/TransportAttrDefs.td b/mlir/include/Transport/IR/TransportAttrDefs.td deleted file mode 100644 index 82f9b6bf89..0000000000 --- a/mlir/include/Transport/IR/TransportAttrDefs.td +++ /dev/null @@ -1,87 +0,0 @@ -// Copyright 2026 Xanadu Quantum Technologies Inc. - -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at - -// http://www.apache.org/licenses/LICENSE-2.0 - -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -#ifndef TRANSPORT_ATTRDEFS -#define TRANSPORT_ATTRDEFS - -include "mlir/IR/AttrTypeBase.td" - -include "Transport/IR/TransportDialect.td" - -//===----------------------------------------------------------------------===// -// Attributes. -//===----------------------------------------------------------------------===// - -// A string field that reads as empty when omitted, so consumers need no null checks. -class Transport_StrField : DefaultValuedParameter<"mlir::StringAttr", - "mlir::StringAttr::get($_ctxt, \"\")", desc>; - -def Transport_NodeAttr : Transport_Attr<"Node", "node"> { - let summary = "A backline participant: a controller or a coprocessor."; - - let parameters = (ins - Transport_StrField<"this node's name; the session registry key when non-empty">:$name, - Transport_StrField<"the peer's address for the out-of-band handshake">:$peer, - OptionalParameter<"mlir::IntegerAttr", - "TCP port for the out-of-band handshake">:$oob_port, - Transport_StrField<"backend plugin the runtime dlopens for this node">:$backend_lib, - Transport_StrField<"backend configuration string, passed through verbatim">:$config, - Transport_StrField<"target triple this node's code is compiled for">:$triple, - Transport_StrField<"executor address when this node runs out of process">:$address, - Transport_StrField<"coprocessor function symbol the backend binds">:$symbol, - OptionalParameter<"mlir::BoolAttr", - "whether this node's code is dispatched to an executor rather than " - "run in the compiling process">:$out_of_process, - OptionalParameter<"mlir::IntegerAttr", "request size in bytes for one round">:$in_bytes, - OptionalParameter<"mlir::IntegerAttr", "reply size in bytes for one round">:$out_bytes, - OptionalParameter<"mlir::IntegerAttr", - "index of this node's work item within the round">:$work_item_idx - ); - - let assemblyFormat = "`<` struct(params) `>`"; - - let extraClassDeclaration = [{ - /// Session registry key: `name` when set and non-empty, else `fallback`. - mlir::StringAttr keyOr(llvm::StringRef fallback) const; - - /// Whether this node's code is dispatched to an executor rather than run in the - /// compiling process. - bool isOutOfProcess() const; - - /// Integer field accessors. - int64_t oobPort() const; - int64_t inBytes() const; - int64_t outBytes() const; - int64_t workItemIdx() const; - }]; -} - -def Transport_BacklineAttr : Transport_Attr<"Backline", "backline"> { - let summary = "A backline placement: one controller and the coprocessors it drives."; - - let parameters = (ins - AttrParameter<"mlir::StringAttr", - "transport carrying the traffic, selecting the compiled backend">:$transport, - AttrParameter<"::catalyst::transport::NodeAttr", - "the controller node that drives the session">:$controller, - OptionalArrayRefParameter<"::catalyst::transport::NodeAttr", - "the coprocessor nodes the controller drives">:$coprocessors - ); - - let assemblyFormat = [{ `<` `transport` `=` $transport `,` `controller` `=` $controller - (`,` `coprocessors` `=` `[` $coprocessors^ `]`)? `>` }]; - let genVerifyDecl = 1; -} - -#endif // TRANSPORT_ATTRDEFS diff --git a/mlir/include/Transport/IR/TransportDialect.td b/mlir/include/Transport/IR/TransportDialect.td index 4e85c380e2..2ba0c970c4 100644 --- a/mlir/include/Transport/IR/TransportDialect.td +++ b/mlir/include/Transport/IR/TransportDialect.td @@ -33,21 +33,9 @@ def Transport_Dialect : Dialect { exchanging memory handles, establishing a data path, and running rounds of request/reply traffic until teardown. - This is what a Backline compiles to. A [PennyLane](https://docs.pennylane.ai/en/stable/) - `Placement` is serialized into the `catalyst.backline` module attribute, naming one - controller and the coprocessors it drives; `inject-transport-session` reads that attribute - and emits the session bring-up and teardown in terms of these ops, - `lower-decode-to-transport` turns a decode into a request/reply round over the session, and - `convert-transport-to-llvm` lowers the result to `__catalyst__transport__*` runtime calls. - A node here is a Backline participant -- a controller or a coprocessor -- and the - placement's transport selects which compiled backend carries the traffic. - - A node the placement dispatches to another machine is shipped and launched through the - `executor` dialect, so a placement that mixes local and dispatched nodes uses both. - - > [!IMPORTANT] - > The transport dialect is experimental and will not maintain API stability between - > releases. Use at your own risk. + A session's endpoints are a controller and a coprocessor, described by the + `#transport.backline` attribute a module carries as `catalyst.backline`. + Every op here lowers to a `__catalyst__transport__*` runtime call. }]; let name = "transport"; @@ -58,24 +46,121 @@ def Transport_Dialect : Dialect { } //===----------------------------------------------------------------------===// -// Type and attribute base classes. +// Enums. +//===----------------------------------------------------------------------===// + +def Transport_Role : I32EnumAttr<"Role", "transport session role", [ + I32EnumAttrCase<"Controller", 0, "controller">, + I32EnumAttrCase<"Coprocessor", 1, "coprocessor"> + ]> { + let cppNamespace = "::catalyst::transport"; +} + + +//===----------------------------------------------------------------------===// +// Types. //===----------------------------------------------------------------------===// -// -// Kept here so TransportTypes.td and TransportAttrDefs.td share them. The defs themselves live in -// those files rather than here: `-gen-dialect-doc` documents whatever attributes, types and enums -// it can reach, and this file is its entry point, so anything left here lands in -// TransportDialect.md ahead of the Types and Attributes sections instead of inside them. class Transport_Type traits = []> : TypeDef { let mnemonic = typeMnemonic; } +// Opaque session handle, parameterized by its role. The role is a compile-time tag +// that selects which role-specific ops the session may take part in. +def Transport_SessionType : Transport_Type<"Session", "session"> { + let summary = "An opaque transport session handle, tagged with its role."; + let parameters = (ins EnumParameter:$role); + let assemblyFormat = "`<` $role `>`"; +} + +def Transport_TokenType : Transport_Type<"Token", "token"> { + let summary = "A handle to an in-flight asynchronous step, awaited with transport.await."; +} + +// Role-constrained session types used by the role-specific ops. +def Transport_ControllerSession : Type< + CPred<"::llvm::isa<::catalyst::transport::SessionType>($_self) && " + "::llvm::cast<::catalyst::transport::SessionType>($_self).getRole() == " + "::catalyst::transport::Role::Controller">, + "controller transport session">; + +def Transport_CoprocessorSession : Type< + CPred<"::llvm::isa<::catalyst::transport::SessionType>($_self) && " + "::llvm::cast<::catalyst::transport::SessionType>($_self).getRole() == " + "::catalyst::transport::Role::Coprocessor">, + "coprocessor transport session">; + +//===----------------------------------------------------------------------===// +// Attributes. +//===----------------------------------------------------------------------===// + class Transport_Attr traits = []> : AttrDef { let mnemonic = attrMnemonic; } +// A string field that reads as empty when omitted, so consumers need no null checks. +class Transport_StrField : DefaultValuedParameter<"mlir::StringAttr", + "mlir::StringAttr::get($_ctxt, \"\")", desc>; + +def Transport_NodeAttr : Transport_Attr<"Node", "node"> { + let summary = "A backline participant: a controller or a coprocessor."; + + let parameters = (ins + Transport_StrField<"this node's name; the session registry key when non-empty">:$name, + Transport_StrField<"the peer's address for the out-of-band handshake">:$peer, + OptionalParameter<"mlir::IntegerAttr", + "TCP port for the out-of-band handshake">:$oob_port, + Transport_StrField<"backend plugin the runtime dlopens for this node">:$backend_lib, + Transport_StrField<"backend configuration string, passed through verbatim">:$config, + Transport_StrField<"target triple this node's code is compiled for">:$triple, + Transport_StrField<"executor address when this node runs out of process">:$address, + Transport_StrField<"coprocessor function symbol the backend binds">:$symbol, + OptionalParameter<"mlir::BoolAttr", + "whether this node's code is dispatched to an executor rather than " + "run in the compiling process">:$out_of_process, + OptionalParameter<"mlir::IntegerAttr", "request size in bytes for one round">:$in_bytes, + OptionalParameter<"mlir::IntegerAttr", "reply size in bytes for one round">:$out_bytes, + OptionalParameter<"mlir::IntegerAttr", + "index of this node's work item within the round">:$work_item_idx + ); + + let assemblyFormat = "`<` struct(params) `>`"; + + let extraClassDeclaration = [{ + /// Session registry key: `name` when set and non-empty, else `fallback`. + mlir::StringAttr keyOr(llvm::StringRef fallback) const; + + /// Whether this node's code is dispatched to an executor rather than run in the + /// compiling process. + bool isOutOfProcess() const; + + /// Integer field accessors. + int64_t oobPort() const; + int64_t inBytes() const; + int64_t outBytes() const; + int64_t workItemIdx() const; + }]; +} + +def Transport_BacklineAttr : Transport_Attr<"Backline", "backline"> { + let summary = "A backline placement: one controller and the coprocessors it drives."; + + let parameters = (ins + AttrParameter<"mlir::StringAttr", + "transport carrying the traffic, selecting the compiled backend">:$transport, + AttrParameter<"::catalyst::transport::NodeAttr", + "the controller node that drives the session">:$controller, + OptionalArrayRefParameter<"::catalyst::transport::NodeAttr", + "the coprocessor nodes the controller drives">:$coprocessors + ); + + let assemblyFormat = [{ `<` `transport` `=` $transport `,` `controller` `=` $controller + (`,` `coprocessors` `=` `[` $coprocessors^ `]`)? `>` }]; + let genVerifyDecl = 1; +} + //===----------------------------------------------------------------------===// // Operation base. //===----------------------------------------------------------------------===// diff --git a/mlir/include/Transport/IR/TransportOps.td b/mlir/include/Transport/IR/TransportOps.td index 7b074ebbad..66ecf5289b 100644 --- a/mlir/include/Transport/IR/TransportOps.td +++ b/mlir/include/Transport/IR/TransportOps.td @@ -19,9 +19,7 @@ include "mlir/IR/OpBase.td" include "mlir/IR/BuiltinAttributes.td" include "mlir/IR/CommonTypeConstraints.td" include "mlir/Interfaces/SideEffectInterfaces.td" -include "Transport/IR/TransportAttrDefs.td" include "Transport/IR/TransportDialect.td" -include "Transport/IR/TransportTypes.td" // A round's payload or reply buffer: a 1-D memref (buffer form) or tensor (value form). def Transport_Buffer : MemRefRankOf<[I1, I8, I16, I32, I64, Index], [1]>; diff --git a/mlir/include/Transport/IR/TransportTypes.td b/mlir/include/Transport/IR/TransportTypes.td deleted file mode 100644 index 93617fa1df..0000000000 --- a/mlir/include/Transport/IR/TransportTypes.td +++ /dev/null @@ -1,60 +0,0 @@ -// Copyright 2026 Xanadu Quantum Technologies Inc. - -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at - -// http://www.apache.org/licenses/LICENSE-2.0 - -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -#ifndef TRANSPORT_TYPES -#define TRANSPORT_TYPES - -include "mlir/IR/AttrTypeBase.td" -include "mlir/IR/EnumAttr.td" - -include "Transport/IR/TransportDialect.td" - -//===----------------------------------------------------------------------===// -// Enums. -//===----------------------------------------------------------------------===// - -def Transport_Role : I32EnumAttr<"Role", "transport session role", [ - I32EnumAttrCase<"Controller", 0, "controller">, - I32EnumAttrCase<"Coprocessor", 1, "coprocessor"> - ]> { - let cppNamespace = "::catalyst::transport"; -} - - -// Opaque session handle, parameterized by its role. The role is a compile-time tag -// that selects which role-specific ops the session may take part in. -def Transport_SessionType : Transport_Type<"Session", "session"> { - let summary = "An opaque transport session handle, tagged with its role."; - let parameters = (ins EnumParameter:$role); - let assemblyFormat = "`<` $role `>`"; -} - -def Transport_TokenType : Transport_Type<"Token", "token"> { - let summary = "A handle to an in-flight asynchronous step, awaited with transport.await."; -} - -// Role-constrained session types used by the role-specific ops. -def Transport_ControllerSession : Type< - CPred<"::llvm::isa<::catalyst::transport::SessionType>($_self) && " - "::llvm::cast<::catalyst::transport::SessionType>($_self).getRole() == " - "::catalyst::transport::Role::Controller">, - "controller transport session">; - -def Transport_CoprocessorSession : Type< - CPred<"::llvm::isa<::catalyst::transport::SessionType>($_self) && " - "::llvm::cast<::catalyst::transport::SessionType>($_self).getRole() == " - "::catalyst::transport::Role::Coprocessor">, - "coprocessor transport session">; - -#endif // TRANSPORT_TYPES From d91188f3a81a0fd3610117720ca6243c0ada7818 Mon Sep 17 00:00:00 2001 From: Shuli Shu <08cnbj@gmail.com> Date: Tue, 8 Sep 2026 15:43:46 -0400 Subject: [PATCH 03/15] revert changes in doc --- doc/code/dialects/Executor/ExecutorDialect.md | 9 +- .../dialects/Transport/TransportAttributes.md | 63 --------- .../dialects/Transport/TransportDialect.md | 130 ++++++++++++++++-- doc/code/dialects/Transport/TransportTypes.md | 25 ---- doc/code/dialects/executor.rst | 5 - doc/code/dialects/transport.rst | 15 -- 6 files changed, 116 insertions(+), 131 deletions(-) delete mode 100644 doc/code/dialects/Transport/TransportAttributes.md delete mode 100644 doc/code/dialects/Transport/TransportTypes.md diff --git a/doc/code/dialects/Executor/ExecutorDialect.md b/doc/code/dialects/Executor/ExecutorDialect.md index ae4df47f9d..6dd91fdb94 100644 --- a/doc/code/dialects/Executor/ExecutorDialect.md +++ b/doc/code/dialects/Executor/ExecutorDialect.md @@ -12,11 +12,4 @@ interacts with an executor service: * Dispatching a previously-shipped qnode kernel * Invoking an arbitrary symbol in a shared library -`dispatch-executor-targets` is what emits these ops. One caller is the `transport` dialect's -bring-up: a [PennyLane](https://docs.pennylane.ai/en/stable/) `Placement` node marked as -running out of process needs its code on the machine that runs it, which is what this dialect -describes. - -> [!IMPORTANT] -> The executor dialect is experimental and will not maintain API stability between -> releases. Use at your own risk. +[TOC] diff --git a/doc/code/dialects/Transport/TransportAttributes.md b/doc/code/dialects/Transport/TransportAttributes.md deleted file mode 100644 index 87dcc368b9..0000000000 --- a/doc/code/dialects/Transport/TransportAttributes.md +++ /dev/null @@ -1,63 +0,0 @@ - - -### BacklineAttr - -_A backline placement: one controller and the coprocessors it drives._ - -Syntax: - -``` -#transport.backline< - mlir::StringAttr, # transport - ::catalyst::transport::NodeAttr, # controller - ::llvm::ArrayRef<::catalyst::transport::NodeAttr> # coprocessors -> -``` - -#### Parameters: - -| Parameter | C++ type | Description | -| :-------: | :-------: | ----------- | -| transport | `mlir::StringAttr` | transport carrying the traffic, selecting the compiled backend | -| controller | `::catalyst::transport::NodeAttr` | the controller node that drives the session | -| coprocessors | `::llvm::ArrayRef<::catalyst::transport::NodeAttr>` | the coprocessor nodes the controller drives | - -### NodeAttr - -_A backline participant: a controller or a coprocessor._ - -Syntax: - -``` -#transport.node< - mlir::StringAttr, # name - mlir::StringAttr, # peer - mlir::IntegerAttr, # oob_port - mlir::StringAttr, # backend_lib - mlir::StringAttr, # config - mlir::StringAttr, # triple - mlir::StringAttr, # address - mlir::StringAttr, # symbol - mlir::BoolAttr, # out_of_process - mlir::IntegerAttr, # in_bytes - mlir::IntegerAttr, # out_bytes - mlir::IntegerAttr # work_item_idx -> -``` - -#### Parameters: - -| Parameter | C++ type | Description | -| :-------: | :-------: | ----------- | -| name | `mlir::StringAttr` | this node's name; the session registry key when non-empty | -| peer | `mlir::StringAttr` | the peer's address for the out-of-band handshake | -| oob_port | `mlir::IntegerAttr` | TCP port for the out-of-band handshake | -| backend_lib | `mlir::StringAttr` | backend plugin the runtime dlopens for this node | -| config | `mlir::StringAttr` | backend configuration string, passed through verbatim | -| triple | `mlir::StringAttr` | target triple this node's code is compiled for | -| address | `mlir::StringAttr` | executor address when this node runs out of process | -| symbol | `mlir::StringAttr` | coprocessor function symbol the backend binds | -| out_of_process | `mlir::BoolAttr` | whether this node's code is dispatched to an executor rather than run in the compiling process | -| in_bytes | `mlir::IntegerAttr` | request size in bytes for one round | -| out_bytes | `mlir::IntegerAttr` | reply size in bytes for one round | -| work_item_idx | `mlir::IntegerAttr` | index of this node's work item within the round | diff --git a/doc/code/dialects/Transport/TransportDialect.md b/doc/code/dialects/Transport/TransportDialect.md index 591bc69c86..de28530489 100644 --- a/doc/code/dialects/Transport/TransportDialect.md +++ b/doc/code/dialects/Transport/TransportDialect.md @@ -9,18 +9,118 @@ between two endpoints: creating a session, bringing up the connection, exchanging memory handles, establishing a data path, and running rounds of request/reply traffic until teardown. -This is what a Backline compiles to. A [PennyLane](https://docs.pennylane.ai/en/stable/) -`Placement` is serialized into the `catalyst.backline` module attribute, naming one -controller and the coprocessors it drives; `inject-transport-session` reads that attribute -and emits the session bring-up and teardown in terms of these ops, -`lower-decode-to-transport` turns a decode into a request/reply round over the session, and -`convert-transport-to-llvm` lowers the result to `__catalyst__transport__*` runtime calls. -A node here is a Backline participant -- a controller or a coprocessor -- and the -placement's transport selects which compiled backend carries the traffic. - -A node the placement dispatches to another machine is shipped and launched through the -`executor` dialect, so a placement that mixes local and dispatched nodes uses both. - -> [!IMPORTANT] -> The transport dialect is experimental and will not maintain API stability between -> releases. Use at your own risk. +This is what a Backline compiles to. A PennyLane `Placement` is serialized +into the `catalyst.backline` module attribute, naming one controller and the +coprocessors it drives; `inject-transport-session` reads that attribute and +emits the session bring-up and teardown in terms of these ops, +`lower-decode-to-transport` turns a decode into a request/reply round over +the session, and `convert-transport-to-llvm` lowers the result to +`__catalyst__transport__*` runtime calls. A node here is a Backline +participant -- a controller or a coprocessor -- and the placement's +transport selects which compiled backend carries the traffic. + +[TOC] + +## Attributes + +### BacklineAttr + +_A backline placement: one controller and the coprocessors it drives._ + +Syntax: + +``` +#transport.backline< + mlir::StringAttr, # transport + ::catalyst::transport::NodeAttr, # controller + ::llvm::ArrayRef<::catalyst::transport::NodeAttr> # coprocessors +> +``` + +#### Parameters: + +| Parameter | C++ type | Description | +| :-------: | :-------: | ----------- | +| transport | `mlir::StringAttr` | transport carrying the traffic, selecting the compiled backend | +| controller | `::catalyst::transport::NodeAttr` | the controller node that drives the session | +| coprocessors | `::llvm::ArrayRef<::catalyst::transport::NodeAttr>` | the coprocessor nodes the controller drives | + +### NodeAttr + +_A backline participant: a controller or a coprocessor._ + +Syntax: + +``` +#transport.node< + mlir::StringAttr, # name + mlir::StringAttr, # peer + mlir::IntegerAttr, # oob_port + mlir::StringAttr, # backend_lib + mlir::StringAttr, # config + mlir::StringAttr, # triple + mlir::StringAttr, # address + mlir::StringAttr, # symbol + mlir::BoolAttr, # out_of_process + mlir::IntegerAttr, # in_bytes + mlir::IntegerAttr, # out_bytes + mlir::IntegerAttr # work_item_idx +> +``` + +#### Parameters: + +| Parameter | C++ type | Description | +| :-------: | :-------: | ----------- | +| name | `mlir::StringAttr` | this node's name; the session registry key when non-empty | +| peer | `mlir::StringAttr` | the peer's address for the out-of-band handshake | +| oob_port | `mlir::IntegerAttr` | TCP port for the out-of-band handshake | +| backend_lib | `mlir::StringAttr` | backend plugin the runtime dlopens for this node | +| config | `mlir::StringAttr` | backend configuration string, passed through verbatim | +| triple | `mlir::StringAttr` | target triple this node's code is compiled for | +| address | `mlir::StringAttr` | executor address when this node runs out of process | +| symbol | `mlir::StringAttr` | coprocessor function symbol the backend binds | +| out_of_process | `mlir::BoolAttr` | whether this node's code is dispatched to an executor rather than run in the compiling process | +| in_bytes | `mlir::IntegerAttr` | request size in bytes for one round | +| out_bytes | `mlir::IntegerAttr` | reply size in bytes for one round | +| work_item_idx | `mlir::IntegerAttr` | index of this node's work item within the round | + +## Types + +### SessionType + +_An opaque transport session handle, tagged with its role._ + +Syntax: + +``` +!transport.session< + ::catalyst::transport::Role # role +> +``` + +#### Parameters: + +| Parameter | C++ type | Description | +| :-------: | :-------: | ----------- | +| role | `::catalyst::transport::Role` | an enum of type Role | + +### TokenType + +_A handle to an in-flight asynchronous step, awaited with transport.await._ + +Syntax: `!transport.token` + + +## Enums + +### Role + +_Transport session role_ + +#### Cases: + +| Symbol | Value | String | +| :----: | :---: | ------ | +| Controller | `0` | controller | +| Coprocessor | `1` | coprocessor | diff --git a/doc/code/dialects/Transport/TransportTypes.md b/doc/code/dialects/Transport/TransportTypes.md deleted file mode 100644 index 7af6a15b2e..0000000000 --- a/doc/code/dialects/Transport/TransportTypes.md +++ /dev/null @@ -1,25 +0,0 @@ - - -### SessionType - -_An opaque transport session handle, tagged with its role._ - -Syntax: - -``` -!transport.session< - ::catalyst::transport::Role # role -> -``` - -#### Parameters: - -| Parameter | C++ type | Description | -| :-------: | :-------: | ----------- | -| role | `::catalyst::transport::Role` | an enum of type Role | - -### TokenType - -_A handle to an in-flight asynchronous step, awaited with transport.await._ - -Syntax: `!transport.token` diff --git a/doc/code/dialects/executor.rst b/doc/code/dialects/executor.rst index d47d34ca3f..f23b98e2f2 100644 --- a/doc/code/dialects/executor.rst +++ b/doc/code/dialects/executor.rst @@ -1,9 +1,4 @@ .. mdinclude:: Executor/ExecutorDialect.md - :end-line: -3 - -.. important:: - The executor dialect is experimental and will not maintain API stability between - releases. Use at your own risk. Types ----- diff --git a/doc/code/dialects/transport.rst b/doc/code/dialects/transport.rst index cb924dd870..3f51287d52 100644 --- a/doc/code/dialects/transport.rst +++ b/doc/code/dialects/transport.rst @@ -1,20 +1,5 @@ .. mdinclude:: Transport/TransportDialect.md - :end-line: -3 -.. important:: - The transport dialect is experimental and will not maintain API stability between - releases. Use at your own risk. - - -Types ------ - -.. mdinclude:: Transport/TransportTypes.md - -Attributes ----------- - -.. mdinclude:: Transport/TransportAttributes.md Operations ---------- From 13e94e9315658babe7cb810aeceaa8cde5eef29c Mon Sep 17 00:00:00 2001 From: Shuli Shu <08cnbj@gmail.com> Date: Tue, 8 Sep 2026 15:44:23 -0400 Subject: [PATCH 04/15] reorder transport dialect sections --- doc/code/dialects/Executor/ExecutorDialect.md | 2 - .../dialects/Transport/TransportDialect.md | 53 +++++++++---------- 2 files changed, 25 insertions(+), 30 deletions(-) diff --git a/doc/code/dialects/Executor/ExecutorDialect.md b/doc/code/dialects/Executor/ExecutorDialect.md index 6dd91fdb94..373d627a9a 100644 --- a/doc/code/dialects/Executor/ExecutorDialect.md +++ b/doc/code/dialects/Executor/ExecutorDialect.md @@ -11,5 +11,3 @@ interacts with an executor service: * Shipping a cross-compiled kernel object file (or other assets) to that endpoint * Dispatching a previously-shipped qnode kernel * Invoking an arbitrary symbol in a shared library - -[TOC] diff --git a/doc/code/dialects/Transport/TransportDialect.md b/doc/code/dialects/Transport/TransportDialect.md index de28530489..d4d89d2b41 100644 --- a/doc/code/dialects/Transport/TransportDialect.md +++ b/doc/code/dialects/Transport/TransportDialect.md @@ -19,7 +19,31 @@ the session, and `convert-transport-to-llvm` lowers the result to participant -- a controller or a coprocessor -- and the placement's transport selects which compiled backend carries the traffic. -[TOC] +## Types + +### SessionType + +_An opaque transport session handle, tagged with its role._ + +Syntax: + +``` +!transport.session< + ::catalyst::transport::Role # role +> +``` + +#### Parameters: + +| Parameter | C++ type | Description | +| :-------: | :-------: | ----------- | +| role | `::catalyst::transport::Role` | an enum of type Role | + +### TokenType + +_A handle to an in-flight asynchronous step, awaited with transport.await._ + +Syntax: `!transport.token` ## Attributes @@ -85,33 +109,6 @@ Syntax: | out_bytes | `mlir::IntegerAttr` | reply size in bytes for one round | | work_item_idx | `mlir::IntegerAttr` | index of this node's work item within the round | -## Types - -### SessionType - -_An opaque transport session handle, tagged with its role._ - -Syntax: - -``` -!transport.session< - ::catalyst::transport::Role # role -> -``` - -#### Parameters: - -| Parameter | C++ type | Description | -| :-------: | :-------: | ----------- | -| role | `::catalyst::transport::Role` | an enum of type Role | - -### TokenType - -_A handle to an in-flight asynchronous step, awaited with transport.await._ - -Syntax: `!transport.token` - - ## Enums ### Role From ead867748ec9cb528c86b8803fdbd0019f9a7be3 Mon Sep 17 00:00:00 2001 From: Shuli Shu <08cnbj@gmail.com> Date: Tue, 8 Sep 2026 15:51:45 -0400 Subject: [PATCH 05/15] update banner: manually added --- doc/code/dialects/Executor/ExecutorDialect.md | 2 +- doc/code/dialects/Transport/TransportDialect.md | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/code/dialects/Executor/ExecutorDialect.md b/doc/code/dialects/Executor/ExecutorDialect.md index 373d627a9a..4124bc1d8c 100644 --- a/doc/code/dialects/Executor/ExecutorDialect.md +++ b/doc/code/dialects/Executor/ExecutorDialect.md @@ -1,4 +1,4 @@ - + # 'executor' Dialect diff --git a/doc/code/dialects/Transport/TransportDialect.md b/doc/code/dialects/Transport/TransportDialect.md index d4d89d2b41..a9daf2024c 100644 --- a/doc/code/dialects/Transport/TransportDialect.md +++ b/doc/code/dialects/Transport/TransportDialect.md @@ -1,4 +1,4 @@ - + # 'transport' Dialect @@ -9,8 +9,9 @@ between two endpoints: creating a session, bringing up the connection, exchanging memory handles, establishing a data path, and running rounds of request/reply traffic until teardown. -This is what a Backline compiles to. A PennyLane `Placement` is serialized -into the `catalyst.backline` module attribute, naming one controller and the +This is what a Backline compiles to. A PennyLane +[`Placement`](https://docs.pennylane.ai/en/latest/code/api/pennylane.backline.Placement.html) +is serialized into the `catalyst.backline` module attribute, naming one controller and the coprocessors it drives; `inject-transport-session` reads that attribute and emits the session bring-up and teardown in terms of these ops, `lower-decode-to-transport` turns a decode into a request/reply round over From b90d3db618a181e0e0b14f532d1fb4d0fddb0434 Mon Sep 17 00:00:00 2001 From: Shuli Shu <08cnbj@gmail.com> Date: Tue, 8 Sep 2026 15:57:05 -0400 Subject: [PATCH 06/15] update styles/formator --- doc/code/dialects/Executor/ExecutorOps.md | 4 ++++ doc/code/dialects/Executor/ExecutorPasses.md | 2 ++ doc/code/dialects/Transport/TransportOps.md | 4 ++++ doc/code/dialects/Transport/TransportPasses.md | 2 ++ 4 files changed, 12 insertions(+) diff --git a/doc/code/dialects/Executor/ExecutorOps.md b/doc/code/dialects/Executor/ExecutorOps.md index ce423a5956..fe9006bb22 100644 --- a/doc/code/dialects/Executor/ExecutorOps.md +++ b/doc/code/dialects/Executor/ExecutorOps.md @@ -1,3 +1,7 @@ + + + + ### `executor.await` (::catalyst::executor::AwaitOp) diff --git a/doc/code/dialects/Executor/ExecutorPasses.md b/doc/code/dialects/Executor/ExecutorPasses.md index c0cb038858..51703a09b6 100644 --- a/doc/code/dialects/Executor/ExecutorPasses.md +++ b/doc/code/dialects/Executor/ExecutorPasses.md @@ -1,3 +1,5 @@ + + ### `-convert-executor-to-llvm` diff --git a/doc/code/dialects/Transport/TransportOps.md b/doc/code/dialects/Transport/TransportOps.md index f07bb389da..11f0f4a120 100644 --- a/doc/code/dialects/Transport/TransportOps.md +++ b/doc/code/dialects/Transport/TransportOps.md @@ -1,3 +1,7 @@ + + + + ### `transport.await` (::catalyst::transport::AwaitOp) diff --git a/doc/code/dialects/Transport/TransportPasses.md b/doc/code/dialects/Transport/TransportPasses.md index 7fcf45c3f8..ed32f1d7fd 100644 --- a/doc/code/dialects/Transport/TransportPasses.md +++ b/doc/code/dialects/Transport/TransportPasses.md @@ -1,3 +1,5 @@ + + ### `-convert-transport-to-llvm` From 1f1d195e1a1db47051f6d5005c3c63876a9fc11f Mon Sep 17 00:00:00 2001 From: Shuli Shu <08cnbj@gmail.com> Date: Tue, 8 Sep 2026 16:04:04 -0400 Subject: [PATCH 07/15] add links in trans --- doc/code/dialects/Transport/TransportDialect.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/code/dialects/Transport/TransportDialect.md b/doc/code/dialects/Transport/TransportDialect.md index a9daf2024c..16d5583649 100644 --- a/doc/code/dialects/Transport/TransportDialect.md +++ b/doc/code/dialects/Transport/TransportDialect.md @@ -10,15 +10,16 @@ exchanging memory handles, establishing a data path, and running rounds of request/reply traffic until teardown. This is what a Backline compiles to. A PennyLane -[`Placement`](https://docs.pennylane.ai/en/latest/code/api/pennylane.backline.Placement.html) +[Placement](https://docs.pennylane.ai/en/latest/code/api/pennylane.backline.Placement.html) is serialized into the `catalyst.backline` module attribute, naming one controller and the -coprocessors it drives; `inject-transport-session` reads that attribute and -emits the session bring-up and teardown in terms of these ops, -`lower-decode-to-transport` turns a decode into a request/reply round over -the session, and `convert-transport-to-llvm` lowers the result to -`__catalyst__transport__*` runtime calls. A node here is a Backline -participant -- a controller or a coprocessor -- and the placement's -transport selects which compiled backend carries the traffic. +coprocessors it drives; [inject-transport-session](Transport/TransportPasses.html#inject-transport-session) +reads that attribute and emits the session bring-up and teardown in terms of these ops, +[lower-decode-to-transport](Transport/TransportPasses.html#lower-decode-to-transport) turns a +decode into a request/reply round over the session, and +[convert-transport-to-llvm](Transport/TransportPasses.html#convert-transport-to-llvm) lowers the +result to `__catalyst__transport__*` runtime calls. A node here is a Backline participant -- a +controller or a coprocessor -- and the placement's transport selects which compiled backend +carries the traffic. ## Types From d8129b99ac9645a4cd22afb4c485ffef5dbbff89 Mon Sep 17 00:00:00 2001 From: Shuli Shu <08cnbj@gmail.com> Date: Tue, 8 Sep 2026 16:13:14 -0400 Subject: [PATCH 08/15] descriptor to match quantum dialect --- doc/code/dialects/Executor/ExecutorDialect.md | 4 ++-- doc/code/dialects/Transport/TransportDialect.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/code/dialects/Executor/ExecutorDialect.md b/doc/code/dialects/Executor/ExecutorDialect.md index 4124bc1d8c..92c64ee086 100644 --- a/doc/code/dialects/Executor/ExecutorDialect.md +++ b/doc/code/dialects/Executor/ExecutorDialect.md @@ -2,9 +2,9 @@ # 'executor' Dialect -_Operations for dispatching kernels and calling symbols on an executor._ +_A executor dialect for dispatching kernels and calling symbols._ -The `executor` dialect models a small set of operations that describe how a host program +The executor dialect models a small set of operations that describe how a host program interacts with an executor service: * Opening a session with an executor endpoint diff --git a/doc/code/dialects/Transport/TransportDialect.md b/doc/code/dialects/Transport/TransportDialect.md index 16d5583649..85b759c8c2 100644 --- a/doc/code/dialects/Transport/TransportDialect.md +++ b/doc/code/dialects/Transport/TransportDialect.md @@ -2,7 +2,7 @@ # 'transport' Dialect -_Typed ops for setting up and driving a transport session._ +_A transport dialect for setting up and driving a data-movement session._ The transport dialect models a connection-oriented data-movement session between two endpoints: creating a session, bringing up the connection, From 7fd470c58ac0305a4388f232520a7a2956940f4b Mon Sep 17 00:00:00 2001 From: Shuli Shu <08cnbj@gmail.com> Date: Tue, 8 Sep 2026 16:21:34 -0400 Subject: [PATCH 09/15] add an changelog entry --- doc/releases/changelog-dev.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/releases/changelog-dev.md b/doc/releases/changelog-dev.md index e792c515d0..a1bdb47daa 100644 --- a/doc/releases/changelog-dev.md +++ b/doc/releases/changelog-dev.md @@ -776,6 +776,7 @@ * The `transport` and `executor` dialects are now documented alongside the other Catalyst dialects. [(#3179)](https://github.com/PennyLaneAI/catalyst/pull/3179) [(#3180)](https://github.com/PennyLaneAI/catalyst/pull/3180) + [(#3197)](https://github.com/PennyLaneAI/catalyst/pull/3197)

Contributors ✍️

From 1aef74077ee4913df24d119fc51d85f173695739 Mon Sep 17 00:00:00 2001 From: Shuli Shu <31480676+multiphaseCFD@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:50:51 -0400 Subject: [PATCH 10/15] Update doc/code/dialects/Executor/ExecutorDialect.md Co-authored-by: Mehrdad Malek <39844030+mehrdad2m@users.noreply.github.com> --- doc/code/dialects/Executor/ExecutorDialect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/code/dialects/Executor/ExecutorDialect.md b/doc/code/dialects/Executor/ExecutorDialect.md index 92c64ee086..c45ba49c13 100644 --- a/doc/code/dialects/Executor/ExecutorDialect.md +++ b/doc/code/dialects/Executor/ExecutorDialect.md @@ -1,4 +1,4 @@ - + # 'executor' Dialect From 5b3620310b1da3d77a74c81a2929cf67f0c6c493 Mon Sep 17 00:00:00 2001 From: Shuli Shu <31480676+multiphaseCFD@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:52:15 -0400 Subject: [PATCH 11/15] Apply suggestion from @multiphaseCFD --- doc/code/dialects/Transport/TransportDialect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/code/dialects/Transport/TransportDialect.md b/doc/code/dialects/Transport/TransportDialect.md index 85b759c8c2..3f6d473eb3 100644 --- a/doc/code/dialects/Transport/TransportDialect.md +++ b/doc/code/dialects/Transport/TransportDialect.md @@ -1,4 +1,4 @@ - + # 'transport' Dialect From f2e02a387ce33e045d6e90e230c338570567d828 Mon Sep 17 00:00:00 2001 From: Shuli Shu <08cnbj@gmail.com> Date: Tue, 8 Sep 2026 16:54:54 -0400 Subject: [PATCH 12/15] triger CIs From e3ac7454bbae21adb91c79fef20016deffdc4afd Mon Sep 17 00:00:00 2001 From: Shuli Shu <31480676+multiphaseCFD@users.noreply.github.com> Date: Tue, 8 Sep 2026 17:08:11 -0400 Subject: [PATCH 13/15] Update doc/code/dialects/Executor/ExecutorDialect.md Co-authored-by: Joseph Lee <40768758+josephleekl@users.noreply.github.com> --- doc/code/dialects/Executor/ExecutorDialect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/code/dialects/Executor/ExecutorDialect.md b/doc/code/dialects/Executor/ExecutorDialect.md index c45ba49c13..409ae43fdb 100644 --- a/doc/code/dialects/Executor/ExecutorDialect.md +++ b/doc/code/dialects/Executor/ExecutorDialect.md @@ -2,7 +2,7 @@ # 'executor' Dialect -_A executor dialect for dispatching kernels and calling symbols._ +_A dialect for dispatching kernels and calling symbols on an executor._ The executor dialect models a small set of operations that describe how a host program interacts with an executor service: From edf15210fc866b5fe25d5c49293edbd201ced074 Mon Sep 17 00:00:00 2001 From: Shuli Shu <31480676+multiphaseCFD@users.noreply.github.com> Date: Tue, 8 Sep 2026 17:08:22 -0400 Subject: [PATCH 14/15] Update doc/code/dialects/Transport/TransportDialect.md Co-authored-by: Joseph Lee <40768758+josephleekl@users.noreply.github.com> --- doc/code/dialects/Transport/TransportDialect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/code/dialects/Transport/TransportDialect.md b/doc/code/dialects/Transport/TransportDialect.md index 3f6d473eb3..7fb337008e 100644 --- a/doc/code/dialects/Transport/TransportDialect.md +++ b/doc/code/dialects/Transport/TransportDialect.md @@ -2,7 +2,7 @@ # 'transport' Dialect -_A transport dialect for setting up and driving a data-movement session._ +_A dialect for setting up and driving data-movement in a transport session._ The transport dialect models a connection-oriented data-movement session between two endpoints: creating a session, bringing up the connection, From efc92cdfa14f3447c8ee0f348fe0a1a87d879eaf Mon Sep 17 00:00:00 2001 From: Shuli Shu <31480676+multiphaseCFD@users.noreply.github.com> Date: Tue, 8 Sep 2026 17:08:32 -0400 Subject: [PATCH 15/15] Update doc/code/dialects/Executor/ExecutorDialect.md Co-authored-by: Joseph Lee <40768758+josephleekl@users.noreply.github.com> --- doc/code/dialects/Executor/ExecutorDialect.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/code/dialects/Executor/ExecutorDialect.md b/doc/code/dialects/Executor/ExecutorDialect.md index 409ae43fdb..c3644f24ef 100644 --- a/doc/code/dialects/Executor/ExecutorDialect.md +++ b/doc/code/dialects/Executor/ExecutorDialect.md @@ -4,7 +4,7 @@ _A dialect for dispatching kernels and calling symbols on an executor._ -The executor dialect models a small set of operations that describe how a host program +The executor dialect models the set of operations that describe how a host program interacts with an executor service: * Opening a session with an executor endpoint