[llvm] [SandboxIR][Doc] Add a Doc file for Sandbox IR (PR #98691)
via llvm-commits
llvm-commits at lists.llvm.org
Fri Jul 12 17:25:58 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/3] [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 0000000000000..0665cc0437a30
--- /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 bf7cdda89a009..ff956234fee25 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/3] 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 0665cc0437a30..6b47bebcd1dac 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 ff956234fee25..86101ffbd9ca5 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.
>From 012ba593504fad2946517c1e3a122da667aad33d Mon Sep 17 00:00:00 2001
From: Vasileios Porpodas <vporpodas at google.com>
Date: Fri, 12 Jul 2024 17:24:56 -0700
Subject: [PATCH 3/3] fixup! fixup! [SandboxIR][Doc] Add a Doc file for Sandbox
IR
---
llvm/docs/SandboxIR.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/llvm/docs/SandboxIR.md b/llvm/docs/SandboxIR.md
index 6b47bebcd1dac..7e96db430b2fc 100644
--- a/llvm/docs/SandboxIR.md
+++ b/llvm/docs/SandboxIR.md
@@ -1,6 +1,6 @@
# 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.
+Sandbox IR is an IR layer on top of LLVM IR that allows you to save/restore its state.
# API
The Sandbox IR API is designed to feel like LLVM, replicating many common API classes and functions to mirror the LLVM API.
@@ -33,7 +33,7 @@ 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)`.
+- Finally we get the Sandbox IR operand that corresponds to `LLVMOp` by querying the map in the Sandbox IR context: `retrun Ctx.getValue(LLVMOp)`.
## Sandbox IR is Write-Through
Sandbox IR is designed to rely on LLVM IR for its state.
More information about the llvm-commits
mailing list