[llvm] [SandboxIR][Doc] Add a Doc file for Sandbox IR (PR #98691)

[Arthur Eubanks via llvm-commits]

================
@@ -0,0 +1,53 @@
+# Sandbox IR: A transactional layer over LLVM IR
+
+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.
+The class hierarchy is similar (but in the `llvm::sandboxir` namespace), for example here is a small part of it:
+```
+namespace sandboxir {
+              Value
+              /  \
+            User BasicBlock ...
+           /   \
+  Instruction Constant
+        /
+     ...
+}
+```
+
+# Design
+
+## Sandbox IR Value <-> LLVM IR Value Mapping
+Each LLVM IR Value maps to a single Sandbox IR Value.
+The reverse is also true in most cases, except for Sandbox IR Instructions that map to more than one LLVM IR Instruction.
+Such instructions can be defined in extensions of the base 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.
+
+- 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 Sandbox IR 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:
----------------
aeubanks wrote:

do you want to mention that you can pass `llvm::Instruction`s to various cost modeling APIs? or is that too specific to put here?

https://github.com/llvm/llvm-project/pull/98691