[BOLT][docs] New backend guide

[aaupov]

Add a brief doc with BOLT-specific guidance for adding a new backend.

[llvmorg-github-actions]

@llvm/pr-subscribers-bolt

Author: Amir Ayupov (aaupov)

Changes

Add a brief doc with BOLT-specific guidance for adding a new backend.

---

Full diff: https://github.com/llvm/llvm-project/pull/211382.diff

2 Files Affected:

• (added) bolt/docs/NewBackend.md (+34)
• (modified) bolt/docs/index.md (+1-1)

diff --git a/bolt/docs/NewBackend.md b/bolt/docs/NewBackend.md
new file mode 100644
index 0000000000000..f236f282909c8
--- /dev/null
+++ b/bolt/docs/NewBackend.md
@@ -0,0 +1,34 @@
+# Adding a New BOLT Backend
+
+A new BOLT backend should follow LLVM's
+[policy for adding a new target](https://llvm.org/docs/DeveloperPolicy.html#adding-a-new-target).
+New BOLT targets are experimental and are not built by default.
+
+Most target-specific work should be isolated in an `MCPlusBuilder`
+implementation under `bolt/lib/Target/<Target>`, together with
+platform-specific relocation handling in `bolt/lib/Core/Relocation.cpp`.
+
+Changes to common infrastructure, particularly `MCPlusBuilder`, must be
+separate from the target changes and land first. Such changes require thorough
+tests and must state their processing-time and peak-memory impact on existing
+targets. Measurements should use large binaries, including at least Clang
+itself.
+
+A backend does not need to implement every `MCPlusBuilder` interface initially.
+However, omitted interfaces must be checked against their callers. Analyses and
+passes that depend on missing functionality, such as stack frame analysis or
+register liveness, must remain disabled.
+
+BOLT passes are not cleanly partitioned into common and target-specific code.
+Enable them for a new target only after auditing their target assumptions and
+proving them stable with target-specific and end-to-end tests. Otherwise, keep
+them disabled.
+
+RISC targets generally need the `LongJmp` pass for branch relaxation. This
+requires correct branch-range checks and short- and long-jump construction,
+with tests covering range boundaries, calls, tail calls, and linker relaxation.
+
+The initial backend should include focused tests for instruction analysis,
+relocations, CFG construction, rewriting, and each enabled pass. Validation
+must include rewriting and executing large real-world binaries, with Clang as
+the minimum large-binary test.
diff --git a/bolt/docs/index.md b/bolt/docs/index.md
index e39892df38523..d1d0894afa68a 100644
--- a/bolt/docs/index.md
+++ b/bolt/docs/index.md
@@ -41,7 +41,7 @@ BOLTAArch64OptimizationStatus
 
 BAT
 BinaryAnalysis
+NewBackend
 PointerAuthDesign
 RuntimeLibrary
 ```
-