[clang] [ClangIR] Add ABI Lowering Design Document (PR #178326)

[Andy Kaylor via cfe-commits]

================
@@ -0,0 +1,602 @@
+# ClangIR ABI Lowering - Design Document
+
+## 1. Introduction
+
+This design describes calling convention lowering that **builds on the GSoC ABI
+Lowering Library** (PR #140112): we use its `abi::Type*` and target ABI logic
+and add an MLIR integration layer (MLIRTypeMapper, ABI lowering pass, and
+dialect rewriters).  The framework relies on the LLVM ABI library in
+`llvm/lib/ABI/` as the single source of truth for ABI classification; MLIR
+dialects use it via an adapter layer.  The design enables CIR to perform
+ABI-compliant calling convention lowering, be reusable by other MLIR dialects
+(particularly FIR), and achieve parity with the CIR incubator for x86_64 and
+AArch64. **What the design is, in concrete terms:** inputs are high-level
+function signatures in CIR, FIR, or other MLIR dialects; outputs are ABI-lowered
+signatures and call sites; lowering runs as an MLIR pass in the compilation
+pipeline, before dialect lowering to LLVM IR or other back ends.
+
+### 1.1 Problem Statement
+
+Calling convention lowering is currently implemented separately for each MLIR
+dialect that needs it.  The CIR incubator has a partial implementation, but it's
+tightly coupled to CIR-specific types and operations, making it unsuitable for
+reuse by other dialects.  This means that FIR (Fortran IR) and future MLIR
+dialects would need to duplicate this complex logic.  While Classic Clang
+CodeGen contains mature ABI lowering code, it cannot be reused directly because
+it's tightly coupled to Clang's AST representation and LLVM IR generation.
+
+### 1.2 Design Goals
+
+Building on the GSoC library and adding an MLIR integration layer avoids
----------------
andykaylor wrote:

```suggestion
Building on the LLVM ABI Lowering library and adding an MLIR integration layer avoids
```

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