llvm/docs/SandboxIR.md

   1 # Sandbox IR: A transactional layer over LLVM IR
   2
   3 Sandbox IR is an IR layer on top of LLVM IR that allows you to save/restore its state.
   4
   5 # Quick Start Notes
   6
   7 Within your LLVM pass:
   8
   9 ``` C++
  10 // 1. Include the necessary Sandbox IR header files.
  11 #include "llvm/SandboxIR/Context.h
  12 #include "llvm/SandboxIR/Function.h
  13
  14 // 2. Create a sandboxir::Context using LLVMContext `LLVMCtx`.
  15 sandboxir::Context Ctx(LLVMCtx);
  16
  17 // 3. Create a sandboxir::Function using LLVM IR Function `LLVMF`.
  18 auto *F = Ctx.createFunction(LLVMF);
  19
  20 // ... Use Sandbox IR in `F` as usual, e.g., iterating, modifying it etc. ...
  21
  22 // 4. Save state when needed.
  23 Ctx.save();
  24
  25 // ... Modify Sandbox IR ...
  26
  27 // 5. Revert to the saved state.
  28 Ctx.revert();
  29 ```
  30
  31 Make sure you link against `SandboxIR` in `CMakeLists.txt`:
  32
  33 ```
  34 LINK_COMPONENTS
  35 ...
  36 SandboxIR
  37 ...
  38 ```
  39
  40 # API
  41 The Sandbox IR API is designed to feel like LLVM, replicating many common API classes and functions to mirror the LLVM API.
  42 The class hierarchy is similar (but in the `llvm::sandboxir` namespace).
  43 For example here is a small part of it:
  44 ```
  45 namespace sandboxir {
  46               Value
  47               /  \
  48             User BasicBlock ...
  49            /   \
  50   Instruction Constant
  51         /
  52      ...
  53 }
  54 ```
  55
  56 # Design
  57
  58 ## Sandbox IR Value <-> LLVM IR Value Mapping
  59 Each LLVM IR Value maps to a single Sandbox IR Value.
  60 The reverse is also true in most cases, except for Sandbox IR Instructions that map to more than one LLVM IR Instruction.
  61 Such instructions can be defined in extensions of the base Sandbox IR.
  62
  63 - Forward mapping: Sandbox IR Value -> LLVM IR Value
  64 Each Sandbox IR Value contains an `llvm::Value *Val` member variable that points to the corresponding LLVM IR Value.
  65
  66 - Reverse mapping: LLVM IR Value -> Sandbox IR Value
  67 This mapping is stored in `sandboxir::Context::LLVMValueToValue`.
  68
  69 For example `sandboxir::User::getOperand(OpIdx)` for a `sandboxir::User *U` works as follows:
  70 - First we find the LLVM User: `llvm::User *LLVMU = U->Val`.
  71 - Next we get the LLVM Value operand: `llvm::Value *LLVMOp = LLVMU->getOperand(OpIdx)`
  72 - Finally we get the Sandbox IR operand that corresponds to `LLVMOp` by querying the map in the Sandbox IR context: `retrun Ctx.getValue(LLVMOp)`.
  73
  74 ## Sandbox IR is Write-Through
  75 Sandbox IR is designed to rely on LLVM IR for its state.
  76 So any change made to Sandbox IR objects directly updates the corresponding LLVM IR.
  77
  78 This has the following benefits:
  79 - It minimizes the replication of state, and
  80 - 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.
  81 - No need for serialization/de-serialization infrastructure as we can rely on LLVM IR for it.
  82 - One can pass actual `llvm::Instruction`s to cost modeling APIs.
  83
  84 Sandbox IR API functions that modify the IR state call the corresponding LLVM IR function that modifies the LLVM IR's state.
  85 For example, for `sandboxir::User::setOperand(OpIdx, sandboxir::Value *Op)`:
  86 - We get the corresponding LLVM User: `llvm::User *LLVMU = cast<llvm::User>(Val)`
  87 - Next we get the corresponding LLVM Operand: `llvm::Value *LLVMOp = Op->Val`
  88 - Finally we modify `LLVMU`'s operand: `LLVMU->setOperand(OpIdx, LLVMOp)
  89
  90 ## IR Change Tracking
  91 Sandbox IR's state can be saved and restored.
  92 This is done with the help of the tracker component that is tightly coupled to the public Sandbox IR API functions.
  93 Please note that nested saves/restores are currently not supported.
  94
  95 To save the state and enable tracking the user needs to call `sandboxir::Context::save()`.
  96 From this point on any change made to the Sandbox IR state will automatically create a change object and register it with the tracker, without any intervention from the user.
  97 The changes are accumulated in a vector within the tracker.
  98
  99 To rollback to the saved state the user needs to call `sandboxir::Context::revert()`.
 100 Reverting back to the saved state is a matter of going over all the accumulated changes in reverse and undoing each individual change.
 101
 102 To accept the changes made to the IR the user needs to call `sandboxir::Context::accept()`.
 103 Internally this will go through the changes and run any finalization required.
 104
 105 Please note that after a call to `revert()` or `accept()` tracking will stop.
 106 To start tracking again, the user needs to call `save()`.