[clang] [clang][docs] Add documentation for EH codegen (PR #176236)

[Eli Friedman via cfe-commits]

================
@@ -0,0 +1,266 @@
+========================================
+LLVM IR Generation for EH and Cleanups
+========================================
+
+.. contents::
+   :local:
+
+Overview
+========
+
+This document describes how Clang's LLVM IR generation represents exception
+handling (EH) and C++ cleanups. It focuses on the data structures and control
+flow patterns used to model normal and exceptional exits, and it outlines how
+the generated IR differs across common ABI models.
+
+Core Model
+==========
+
+EH and cleanup handling is centered around an ``EHScopeStack`` that records
+nested scopes for:
+
+- **Cleanups**, which run on normal control flow, exceptional control flow, or
+  both. These are used for destructors, full-expression cleanups, and other
+  scope-exit actions.
+- **Catch scopes**, which represent ``try``/``catch`` handlers.
+- **Filter scopes**, used to model dynamic exception specifications and some
+  platform-specific filters.
+- **Terminate scopes**, used for ``noexcept`` and similar termination paths.
+
+Each cleanup is a small object with an ``Emit`` method. When a cleanup scope is
+popped, the IR generator decides whether it must materialize a normal cleanup
+block (for fallthrough, branch-through, or unresolved ``goto`` fixups) and/or an
+EH cleanup entry (when exceptional control flow can reach the cleanup). This
+results in a flattened CFG where cleanup lifetime is represented by the blocks
+and edges that flow into those blocks.
+
+Key Components
+==============
+
+The LLVM IR generation for EH and cleanups is spread across several core
+components:
+
+- ``CodeGenModule`` owns module-wide state such as the LLVM module, target
+  information, and the selected EH personality function. It provides access to
+  ABI helpers via ``CGCXXABI`` and target-specific hooks.
+- ``CodeGenFunction`` manages per-function state and IR building. It owns the
+  ``EHScopeStack``, tracks the current insertion point, and emits blocks, calls,
+  and branches. Most cleanup and EH control flow is built here.
+- ``EHScopeStack`` is the central stack of scopes used to model EH and cleanup
+  semantics. It stores ``EHCleanupScope`` entries for cleanups, along with
+  ``EHCatchScope``, ``EHFilterScope``, and ``EHTerminateScope`` for handlers and
+  termination logic.
+- ``EHCleanupScope`` stores the cleanup object plus state data (active flags,
+  fixup depth, and enclosing scope links). When a cleanup scope is popped,
+  ``CodeGenFunction`` decides whether to emit a normal cleanup block, an EH
+  cleanup entry, or both.
+- Cleanup emission helpers implement the mechanics of branching through
+  cleanups, threading fixups, and emitting cleanup blocks.
+- Exception emission helpers implement landing pads, dispatch blocks,
+  personality selection, and helper routines for try/catch, filters, and
+  terminate handling.
+- ``CGCXXABI`` (and its ABI-specific implementations such as
+  ``ItaniumCXXABI`` and ``MicrosoftCXXABI``) provide ABI-specific lowering for
+  throws, catch handling, and destructor emission details.
+- C++ expression, class, and statement emission logic drives construction and
+  destruction, and is responsible for pushing/popping cleanups in response to
+  AST constructs.
+
+These components interact along a consistent pattern: AST traversal in
----------------
efriedma-quic wrote:

The phrase "These components interact along a consistent pattern" isn't saying anything.

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