[llvm] [SandboxIR][Doc] Add a Doc file for Sandbox IR (PR #98691)
via llvm-commits
llvm-commits at lists.llvm.org
Fri Jul 12 16:33:44 PDT 2024
https://github.com/vporpo updated https://github.com/llvm/llvm-project/pull/98691
>From 85c16beb3eadb7e23c1795d07b4638eb2884c957 Mon Sep 17 00:00:00 2001
From: Vasileios Porpodas <vporpodas at google.com>
Date: Fri, 12 Jul 2024 13:19:14 -0700
Subject: [PATCH 1/2] [SandboxIR][Doc] Add a Doc file for Sandbox IR
This is under User Guides > Additional Topics > Sandbox IR.
---
llvm/docs/SandboxIR.md | 53 ++++++++++++++++++++++++++++++++++++++++
llvm/docs/UserGuides.rst | 5 ++++
2 files changed, 58 insertions(+)
create mode 100644 llvm/docs/SandboxIR.md
diff --git a/llvm/docs/SandboxIR.md b/llvm/docs/SandboxIR.md
new file mode 100644
index 000000000000..0665cc0437a3
--- /dev/null
+++ b/llvm/docs/SandboxIR.md
@@ -0,0 +1,53 @@
+# Sandbox IR: A transactional layer over LLVM IR
+
+Sandbox IR is an IR layer on top of LLVM IR that allow you to save/restore its state.
+
+# API
+The Sandbox IR API is designed to make it feel like LLVM.
+So Sandbox IR replicates many common API classes and functions to mirror the LLVM API.
+The class hierarchy is quite similar (but in the `sandboxir` namespace), for example here is a small part of it:
+```
+namespace sandboxir {
+ Value
+ / \
+ User BasicBlock ...
+ / \
+ Instruction Constant
+ /
+ ...
+}
+```
+
+Sandbox IR is also using a similar type system with `isa<>, cast<>, dyn_cast<>`.
+
+# Design
+
+## Sandbox IR Value <-> LLVM IR Value Mapping
+LLVM IR and Sandbox IR are always in sync.
+
+- Forward mapping: Sandbox IR Value -> LLVM IR Value
+Each Sandbox IR Value contains an `llvm::Value *Val` member variable that points to the corresponding LLVM IR Value.
+
+- Reverse mapping: LLVM IR Value -> Sandbox IR Value
+This mapping is stored in `sandboxir::Context::LLVMValueToValue`.
+
+For example `sandboxir::User::getOperand(OpIdx)` for a `sandboxir::User * U` works as follows:
+- First we find the LLVM User: `llvm::User * LLVMU = U->Val`.
+- Next we get the LLVM Value operand: `llvm::Value *LLVMOp = LLVMU->getOperand(OpIdx)`
+- Finally we get the Sandbox IR operand that corresponds to `LLVMOp` by querying the map in the SandboxIR context: `retrun Ctx.getValue(LLVMOp)`.
+
+## Sandbox IR is Write-Through
+Sandbox IR is designed to rely on LLVM IR for its state.
+So any change made to Sandbox IR objects directly updates the corresponding LLVM IR.
+
+This has the following benefits:
+- It minimizes the replication of state, and
+- It makes sure that Sandbox IR and LLVM IR are always in sync, which helps avoid bugs and removes the need for a lowering step.
+- No need for serialization/de-serialization infrastructure as we can rely on LLVM IR for it.
+
+The implementation is straight-forward:
+Sandbox IR API functions that modify the IR state call the corresponding LLVM IR function that modifies the LLVM IR's state.
+For example, for `sandboxir::User::setOperand(OpIdx, sandboxir::Value *Op)`:
+- We get the corresponding LLVM User: `llvm::User *LLVMU = cast<llvm::User>(Val)`
+- Next we get the corresponding LLVM Operand: `llvm::Value *LLVMOp = Op->Val`
+- Finally we modify `LLVMU`'s operand: `LLVMU->setOperand(OpIdx, LLVMOp)`.
diff --git a/llvm/docs/UserGuides.rst b/llvm/docs/UserGuides.rst
index bf7cdda89a00..ff956234fee2 100644
--- a/llvm/docs/UserGuides.rst
+++ b/llvm/docs/UserGuides.rst
@@ -67,6 +67,7 @@ intermediate LLVM representation.
RISCV/RISCVVectorExtension
SourceLevelDebugging
SPIRVUsage
+ SandboxIR
StackSafetyAnalysis
SupportLibrary
TableGen/index
@@ -192,6 +193,7 @@ Optimizations
This document specifies guidelines for contributions for InstCombine and
related passes.
+
Code Generation
---------------
@@ -288,3 +290,6 @@ Additional Topics
:doc:`RISCV/RISCVVectorExtension`
This document describes how the RISC-V Vector extension can be expressed in LLVM IR and how code is generated for it in the backend.
+
+:doc:`Sandbox IR <SandboxIR>`
+ Describes the design and usage of Sandbox IR, a transactional layer over LLVM IR.
>From 1ee7c005fdf8cadab4dff50654cae027f247720c Mon Sep 17 00:00:00 2001
From: Vasileios Porpodas <vporpodas at google.com>
Date: Fri, 12 Jul 2024 16:32:33 -0700
Subject: [PATCH 2/2] fixup! [SandboxIR][Doc] Add a Doc file for Sandbox IR
---
llvm/docs/SandboxIR.md | 17 ++++++++---------
llvm/docs/UserGuides.rst | 2 +-
2 files changed, 9 insertions(+), 10 deletions(-)
diff --git a/llvm/docs/SandboxIR.md b/llvm/docs/SandboxIR.md
index 0665cc0437a3..6b47bebcd1da 100644
--- a/llvm/docs/SandboxIR.md
+++ b/llvm/docs/SandboxIR.md
@@ -3,9 +3,8 @@
Sandbox IR is an IR layer on top of LLVM IR that allow you to save/restore its state.
# API
-The Sandbox IR API is designed to make it feel like LLVM.
-So Sandbox IR replicates many common API classes and functions to mirror the LLVM API.
-The class hierarchy is quite similar (but in the `sandboxir` namespace), for example here is a small part of it:
+The Sandbox IR API is designed to feel like LLVM, replicating many common API classes and functions to mirror the LLVM API.
+The class hierarchy is similar (but in the `llvm::sandboxir` namespace), for example here is a small part of it:
```
namespace sandboxir {
Value
@@ -18,12 +17,12 @@ namespace sandboxir {
}
```
-Sandbox IR is also using a similar type system with `isa<>, cast<>, dyn_cast<>`.
-
# Design
## Sandbox IR Value <-> LLVM IR Value Mapping
-LLVM IR and Sandbox IR are always in sync.
+Each LLVM IR Value maps to a single Sandbox IR Value.
+The reverse is also true in most cases, except for multi-Instruction Sandbox IR Instructions that may be defined in extensions the Sandbox IR.
+
- Forward mapping: Sandbox IR Value -> LLVM IR Value
Each Sandbox IR Value contains an `llvm::Value *Val` member variable that points to the corresponding LLVM IR Value.
@@ -31,7 +30,7 @@ Each Sandbox IR Value contains an `llvm::Value *Val` member variable that points
- Reverse mapping: LLVM IR Value -> Sandbox IR Value
This mapping is stored in `sandboxir::Context::LLVMValueToValue`.
-For example `sandboxir::User::getOperand(OpIdx)` for a `sandboxir::User * U` works as follows:
+For example `sandboxir::User::getOperand(OpIdx)` for a `sandboxir::User *U` works as follows:
- First we find the LLVM User: `llvm::User * LLVMU = U->Val`.
- Next we get the LLVM Value operand: `llvm::Value *LLVMOp = LLVMU->getOperand(OpIdx)`
- Finally we get the Sandbox IR operand that corresponds to `LLVMOp` by querying the map in the SandboxIR context: `retrun Ctx.getValue(LLVMOp)`.
@@ -45,9 +44,9 @@ This has the following benefits:
- It makes sure that Sandbox IR and LLVM IR are always in sync, which helps avoid bugs and removes the need for a lowering step.
- No need for serialization/de-serialization infrastructure as we can rely on LLVM IR for it.
-The implementation is straight-forward:
+The implementation is straightforward:
Sandbox IR API functions that modify the IR state call the corresponding LLVM IR function that modifies the LLVM IR's state.
For example, for `sandboxir::User::setOperand(OpIdx, sandboxir::Value *Op)`:
- We get the corresponding LLVM User: `llvm::User *LLVMU = cast<llvm::User>(Val)`
- Next we get the corresponding LLVM Operand: `llvm::Value *LLVMOp = Op->Val`
-- Finally we modify `LLVMU`'s operand: `LLVMU->setOperand(OpIdx, LLVMOp)`.
+- Finally we modify `LLVMU`'s operand: `LLVMU->setOperand(OpIdx, LLVMOp)
diff --git a/llvm/docs/UserGuides.rst b/llvm/docs/UserGuides.rst
index ff956234fee2..86101ffbd9ca 100644
--- a/llvm/docs/UserGuides.rst
+++ b/llvm/docs/UserGuides.rst
@@ -292,4 +292,4 @@ Additional Topics
This document describes how the RISC-V Vector extension can be expressed in LLVM IR and how code is generated for it in the backend.
:doc:`Sandbox IR <SandboxIR>`
- Describes the design and usage of Sandbox IR, a transactional layer over LLVM IR.
+ This document describes the design and usage of Sandbox IR, a transactional layer over LLVM IR.
More information about the llvm-commits
mailing list