feat(port): 平台相关的换成 openkal 接口 —— 立规矩,并做掉 std::atomic 的等待

⭐ 规矩三条,写在 llvm/PATCHES.md 里,与 openkal-musl 的一致:

1. **可以动源码。** 移植就是动源码;假装不动只会把差异藏进别处。
2. **动过的地方要标注清楚。** 每一处夹在 `// ─── openkal ─── BEGIN/END` 之间,
   `grep -rn "openkal ─── BEGIN" llvm/` 一次数完。
3. **能不动的就不动。** 上游能自己走对的路,让它走。

判据:换的是「平台」不是「库」。每一处替换必须能填进这句话 ——「upstream 在这里
问『这是哪个 OS』,而这个问题真正的答案是 openkal 的 <接口>」。⚠️ 填不进去的不要
动:sizeof(long)、int64_t 的拼法、目标格式不是「下面是谁」,是目标自己的定义。

## 已换:std::atomic 的等待与唤醒

上游一条链,五个分支,四个操作系统(SYS_futex / _umtx_op / futex / WaitOnAddress
/ 完全不等待)。openkal 的答案是 kal_task_wait / kal_task_wake —— 规范管它叫挂起
原语,而它在每一个目标上是同样的两个调用。

平台面**恰好两个函数**,其余 495 行全可移植 ⇒ 原地打标记的补丁,漂移面从 495 行
缩到约 50 行,而不是整文件拷贝。

⚠️ 它本来就已经到 openkal 了,只是绕了一圈:Linux 上发 SYS_futex,musl 的 port
拦下来,__okm_futex 调 kal_task_wait。直接走去掉那一圈,并让另外两种目标格式也
能用 —— 在那里没有系统调用可拦。

## 三处配套,而每一处都是「同一个事实的第二个说法」

- port/include/__atomic/contention_t.h —— 竞争计数器的宽度跟随挂起原语(4 字节)
- port/include/__atomic/atomic_waitable_traits.h —— ⚠️ **只改前者不够**:开了
  _LIBCPP_ABI_ATOMIC_WAIT_NATIVE_BY_SIZE 之后实例化清单来自这个宏而不是
  sizeof(__cxx_contention_t)。两个头陈述一个事实,改了读者先找到的那个,报错一字
  不变。(这是本移植第二次遇到「一个事实走两条通道」,链接线是第一次。)
- OPENKAL_HAS_TASK —— ⚠️ 只提供 core 的实现没有挂起原语,实测裸机链接停在
  undefined symbol: kal_task_wait。那是 6.1 在工作,不是缺陷;答案是落回上游那条
  本来就正确的分支(单执行上下文的机器上 atomic::wait 没有东西可等,轮询是准确的
  实现而不是替代品)。⚠️ 这与 openkal-musl 的 OKM_HAS_TASK 是同一个事实,说了
  第二遍 —— 因为现在有第二个消费者。

## PATCHES.md 里比「已换」更重要的一节:不需要动的

整棵树 #include <windows.h> 共 19 处。12 处守在 _LIBCPP_WIN32API 上,已由
port/include/__config 撤回 ⇒ **自己落到 POSIX 分支,而那条本来就在 openkal 上**
(它调 fopen/clock_gettime/pthread_*,那些是 musl)。2 处守在 __SEH__ 上,已由
-fdwarf-exceptions 绕开。

⇒ 这就是为什么整份移植是几十行而不是把 libc++ 重做一遍。**先问「上游有没有一条
路已经通向 openkal」,再考虑换。**

已验证三个目标:宿主 ✅ / 裸机 riscv64 ✅ / macOS 交叉产出 Mach-O arm64 ✅
(外部符号仍是那三个)。

Author: speak-agent

llvm/PATCHES.md

@@ -0,0 +1,98 @@
+# 这棵 vendored 树被动过的地方
+
+⭐ **规矩三条,与 `openkal-musl` 的一致:**
+
+1. **可以动源码。** 移植就是动源码;假装不动只会把差异藏进别处。
+2. **动过的地方要标注清楚。** 每一处都夹在
+   `// ─── openkal ─── BEGIN` / `// ─── openkal ─── END` 之间,`grep` 一次能数完。
+3. **能不动的就不动。** 上游能自己走对的路,让它走 —— 见下面的「不需要动的」。
+
+```sh
+# 数一遍
+grep -rn "openkal ─── BEGIN" llvm/
+```
+
+---
+
+## 判据:换的是「平台」,不是「库」
+
+上游按**操作系统**选实现;openkal 的答案按**下面配置的是什么**。所以每一处替换
+都必须能填进这句话:
+
+> upstream 在这里问「这是哪个 OS」,而这个问题真正的答案是 openkal 的 `<接口>`。
+
+⚠️ 填不进去的**不要动**。`sizeof(long)`、`int64_t` 的拼法、目标格式、调用约定
+不是「下面是谁」,是**目标自己的定义** —— 那些归 C 库(`musl-generated/` 按
+(arch, os) 分档),不归这里。
+
+---
+
+## 已替换
+
+### `libcxx/src/atomic.cpp` — `std::atomic` 的等待与唤醒
+
+上游一条链,五个分支,四个操作系统:
+
+```
+__linux__   → syscall(SYS_futex, …)
+__FreeBSD__ → _umtx_op
+__OpenBSD__ → futex()
+_WIN32      → WaitOnAddress / WakeByAddressSingle
+否则         → 完全不等待(自旋)
+```
+
+平台面**恰好两个函数**(`__platform_wait_on_address` / `__platform_wake_by_address`),
+其余 495 行全是可移植的 —— 所以这里是**原地打标记的补丁**而不是整文件拷贝,
+漂移面从 495 行缩到约 50 行。
+
+openkal 的答案是 `kal_task_wait` / `kal_task_wake` —— 规范管它叫**挂起原语**,
+而它在每一个目标上是同样的两个调用,**包括底下没有操作系统的那个**。
+
+⚠️ **它本来就已经到 openkal 了,只是绕了一圈。** 在 Linux 上,上游那条分支发
+`SYS_futex`,openkal-musl 的 port 拦下这个系统调用,它的 `__okm_futex` 调
+`kal_task_wait`。直接走去掉了那一圈,并且让另外两种目标格式也能用 —— 在那里
+「拦系统调用」没有系统调用可拦。
+
+⚠️ 两处细节按上游的语义保留:两秒的默认超时(没有超时的等待注意不到与它竞争的
+唤醒),以及 `-1` 表示「全部唤醒」(上游写作 `INT_MAX`,openkal 的计数是
+`kal_uintptr`,所以按回绕写)。
+
+---
+
+## 不需要动的 —— 而这一节比上一节重要
+
+⭐ 整棵树里 `#include <windows.h>` 共 **19 处**。按守卫分类:
+
+| 守卫 | 处数 | 怎么解决的 |
+|---|---|---|
+| `_LIBCPP_WIN32API` | **12** | ✅ `port/include/__config` 撤回了它 → **自己落到 POSIX 分支** |
+| `__SEH__` / `_LIBUNWIND_SUPPORT_DWARF_UNWIND` | 2 | ✅ `-fdwarf-exceptions`,异常机制跟随我们带的 unwinder |
+| 裸 `_WIN32` | 3 | 1 处已换(见上),2 处待办(见下) |
+
+⭐⭐ **12 处不用换,因为 libc++ 的 POSIX 分支本来就已经在 openkal 上了。** 它调
+`fopen` / `clock_gettime` / `pthread_*`,那些是 musl,而 musl 就在 openkal 上。
+让谓词答对,它自己就走到那条路。
+
+⇒ 这就是为什么整份移植是几十行而不是把 libc++ 重做一遍。**先问「上游有没有一条
+路已经通向 openkal」,再考虑换。**
+
+---
+
+## 待办
+
+| 文件 | 平台面 | openkal 的答案 |
+|---|---|---|
+| `libunwind/src/RWMutex.hpp` | 读写锁 | `openkal.task`;或 `_LIBUNWIND_HAS_NO_THREADS`(unwinder 的锁只在缓存上) |
+| `libunwind/src/AddressSpace.hpp` | 段查询的 Windows 分支 | 已由 DWARF 路线绕开,待确认没有残留 |
+
+---
+
+## 与 `port/include/` 的分工
+
+| | 放哪 | 为什么 |
+|---|---|---|
+| **头文件**里的平台分派 | `port/include/` 覆盖 | 靠 include 顺序遮蔽,vendored 树逐字节不动,**不随上游漂移** |
+| **源码**里的平台分派 | 本文件记录的原地标记 | 消费者不 include `.cpp`,遮蔽不了 |
+
+⚠️ 顺序是有偏好的:**能用覆盖就别用补丁**。覆盖的漂移面是零,补丁的漂移面是被
+标记的那几十行。

llvm/libcxx/src/atomic.cpp

@@ -19,7 +19,52 @@
 
 #include "include/apple_availability.h"
 
-#ifdef __linux__
+// ─── openkal ─── BEGIN ────────────────────────────────────────────────────────
+//
+// This file's platform surface is exactly two functions, and the chain below
+// answers them once per operating system: Linux by `SYS_futex`, FreeBSD by
+// `_umtx_op`, OpenBSD by `futex`, Windows by `WaitOnAddress`, and everything
+// else by not waiting at all.
+//
+// openkal answers them once, full stop. `kal_task_wait` / `kal_task_wake` ARE
+// this primitive — the specification calls it the suspension primitive — and
+// they are the same two calls on every target this library is built for,
+// including one with no operating system underneath.
+//
+// ⚠️ IT WAS ALREADY REACHING openkal ON ONE TARGET, THE LONG WAY ROUND. On
+// Linux the branch below issues `SYS_futex`, openkal-musl's port intercepts the
+// system call, and its `__okm_futex` calls `kal_task_wait`. Going directly
+// removes that indirection AND makes the other object formats work, where the
+// interception has no system call to intercept.
+//
+// See llvm/PATCHES.md for every region of this vendored tree that is marked
+// like this and why.
+// ⚠️ AND ONLY WHEN THE IMPLEMENTATION BENEATH PROVIDES `openkal.task`.
+//
+// openkal is composable: an implementation provides an interface in whole or
+// not at all, and one with a single execution context has no suspension
+// primitive to offer — clause 6.2 says the remedy is that its absence be
+// expressed by its absence, so `kal_task_wait` is simply not there.
+//
+// ⚠️ Measured 2026-08-23 on riscv64 over SBI, after this block was written
+// without the guard: everything compiled and the link stopped on
+// `undefined symbol: kal_task_wait`. That is 6.1 working, not a defect — and
+// the answer is not to weaken openkal but to fall through to the branch that
+// was already correct there. `std::atomic::wait` on a machine with one
+// execution context has nothing to wait FOR; upstream's baseline polls, and
+// polling is the accurate implementation rather than a stand-in.
+//
+// ⚠️ THIS IS THE SAME FACT openkal-musl STATES AS `OKM_HAS_TASK`, said a second
+// time because there is now a second consumer. A manifest that could name the
+// interfaces an implementation provides would let both read one declaration;
+// today each states it for itself.
+#if defined(_LIBCPP_HAS_MUSL_LIBC) && OPENKAL_HAS_TASK
+
+// No headers: openkal's are reached through the declarations below, and the two
+// entry points are declared where they are used.
+
+#elif defined(__linux__)
+// ─── openkal ─── END ──────────────────────────────────────────────────────────
 
 #  include <linux/futex.h>
 #  include <sys/syscall.h>
@@ -66,7 +111,60 @@ _LIBCPP_BEGIN_NAMESPACE_STD
 
 struct NoTimeout {};
 
-#ifdef __linux__
+// ─── openkal ─── BEGIN ────────────────────────────────────────────────────────
+#if defined(_LIBCPP_HAS_MUSL_LIBC) && OPENKAL_HAS_TASK
+
+// ⚠️ A name for it. `__UINTPTR_TYPE__` expands to several tokens
+// (`long unsigned int`), so it cannot be written as a function-style cast —
+// the compiler reports `expected '(' for function-style cast`, which does not
+// mention the macro. One alias, used everywhere below.
+using __okl_uptr = __UINTPTR_TYPE__;
+
+extern "C" {
+// Declared rather than included: openkal's headers are C, this file is C++ in
+// libc++'s own namespace, and two declarations are cheaper than arranging for a
+// header to be reachable from inside `_LIBCPP_BEGIN_NAMESPACE_STD`.
+//
+// ⚠️ The widths are openkal's own (`kal_u32`, `kal_u64`), spelled here as what
+// the specification says they are. openkal derives them from the compiler for
+// exactly this reason: a consumer can restate them without a header and cannot
+// get a different type than the implementation was built with.
+int kal_task_wait(const unsigned int* __word, unsigned int __expected, unsigned long long __timeout_ns);
+int kal_task_wake(const unsigned int* __word, __okl_uptr __count, __okl_uptr* __woken);
+}
+
+template <std::size_t _Size, class MaybeTimeout>
+static void __platform_wait_on_address(void const* __ptr, void const* __val, MaybeTimeout maybe_timeout_ns) {
+  static_assert(_Size == 4, "Can only wait on 4 bytes value");
+  alignas(unsigned int) char buffer[_Size];
+  std::memcpy(&buffer, const_cast<const void*>(__val), _Size);
+  // ⚠️ The same two-second default the Linux branch uses, and for the same
+  // reason: a wait that never times out cannot notice a wake it raced with.
+  // Zero means "no timeout" to openkal, so the default is stated rather than
+  // passed through.
+  unsigned long long __ns = 2'000'000'000ull;
+  if constexpr (!is_same_v<MaybeTimeout, NoTimeout>) {
+    __ns = static_cast<unsigned long long>(maybe_timeout_ns);
+  }
+  kal_task_wait(reinterpret_cast<const unsigned int*>(__ptr),
+                *reinterpret_cast<const unsigned int*>(&buffer),
+                __ns);
+}
+
+template <std::size_t _Size>
+static void __platform_wake_by_address(void const* __ptr, bool __notify_one) {
+  static_assert(_Size == 4, "Can only wake up on 4 bytes value");
+  // ⚠️ `-1` for "all", which is openkal's spelling of what the other branches
+  // write as `INT_MAX`. The count is a `kal_uintptr`, so the maximum is stated
+  // as the wrap rather than as a header's constant.
+  __okl_uptr __woken = 0;
+  kal_task_wake(reinterpret_cast<const unsigned int*>(__ptr),
+                __notify_one ? __okl_uptr(1) : __okl_uptr(-1),
+                &__woken);
+}
+
+#elif defined(__linux__)
+// ─── openkal ─── END ──────────────────────────────────────────────────────────
 
 template <std::size_t _Size, class MaybeTimeout>
 static void __platform_wait_on_address(void const* __ptr, void const* __val, MaybeTimeout maybe_timeout_ns) {

mcpp.toml

@@ -288,7 +288,11 @@ include_dirs = ["llvm-generated/freestanding"]
 #   The symbols are `__eh_frame_start` / `__eh_frame_end` (and the `_hdr_`
 #   pair), and AddressSpace.hpp carries the linker script fragment that defines
 #   them. examples/same-source/link.ld is that fragment.
-cxxflags = ["-D_LIBUNWIND_IS_BAREMETAL=1"]
+# ⚠️ `-U` then `-D`: the package-wide list above already defined it, and a
+# second `-D` of a different value is a redefinition warning rather than an
+# override.
+cxxflags = ["-D_LIBUNWIND_IS_BAREMETAL=1", "-UOPENKAL_HAS_TASK", "-DOPENKAL_HAS_TASK=0"]
+cflags   = ["-UOPENKAL_HAS_TASK", "-DOPENKAL_HAS_TASK=0"]
 # ⚠️ THE FLAG BELONGS TO THIS PACKAGE AND LANDS ON THE CONSUMER'S LINK.
 #
 # `_LIBUNWIND_IS_BAREMETAL` above makes the unwinder read `__eh_frame_hdr_start`
@@ -380,6 +384,18 @@ cxxflags = [
   # macOS target then failed on `unknown type name 'Dl_info'` — the same fact,
   # asked again, at a place that had not been told.
   "-D_LIBUNWIND_USE_DLADDR=0",
+  # ⭐ WHETHER THE IMPLEMENTATION BENEATH PROVIDES `openkal.task`.
+  #
+  # `llvm/libcxx/src/atomic.cpp` asks openkal for the suspension primitive
+  # rather than asking an operating system — see llvm/PATCHES.md. An
+  # implementation with a single execution context has none to offer, and
+  # openkal expresses that by the interface being absent, so the C++ runtime has
+  # to know before it is compiled.
+  #
+  # ⚠️ THE SAME FACT openkal-musl STATES AS `OKM_HAS_TASK`. Two consumers, two
+  # declarations, because a manifest cannot yet read what an implementation
+  # provides. Cleared for `cfg(os = "none")` below, exactly as musl's is.
+  "-DOPENKAL_HAS_TASK=1",
   # ⭐ musl's non-standard names live behind this, and they are not optional for
   # libc++: the locale backend calls `vasprintf`, `strtof_l`, `strtod_l`,
   # `strtold_l`, and libc++abi's guard reaches `syscall`. All of them are musl's

port/include/__atomic/atomic_waitable_traits.h

@@ -0,0 +1,36 @@
+// Which widths the platform's wait primitive serves natively.
+//
+// ⭐ THE COMPANION TO `__atomic/contention_t.h` BESIDE THIS FILE, AND BOTH ARE
+// NEEDED — WHICH IS THE FINDING.
+//
+// Upstream answers by operating system: 4 on Linux, 4 and 8 on Apple, 8 on
+// FreeBSD and Windows. `atomic.cpp` instantiates its templates at exactly these
+// widths, and its platform block `static_assert`s the one it can serve.
+//
+// openkal's suspension primitive is `kal_task_wait(const kal_u32*, …)` — four
+// bytes, on every target, because that is what the specification says it takes.
+//
+// ⚠️ SETTING THE CONTENTION TYPE ALONE DID NOT WORK, and the way it failed is
+// worth keeping. Measured 2026-08-23: after `__cxx_contention_t` was made
+// `int32_t` here, the same assertion came back unchanged —
+//
+//     static assertion failed due to requirement '8UL == 4'
+//
+// — because when `_LIBCPP_ABI_ATOMIC_WAIT_NATIVE_BY_SIZE` is on, the
+// instantiation list is THIS macro and not `sizeof(__cxx_contention_t)`. Two
+// headers state one fact, and fixing the one a reader finds first leaves the
+// error identical. (This is the second time in this port that a fact reached
+// its destination through two channels; the link line was the first.)
+#ifndef OPENKAL_LIBCXX_ATOMIC_WAITABLE_TRAITS_OVERLAY
+#define OPENKAL_LIBCXX_ATOMIC_WAITABLE_TRAITS_OVERLAY
+
+#include <__config>
+
+#if _LIBCPP_HAS_MUSL_LIBC
+// The width openkal serves, stated before upstream's chain can answer by OS.
+#  define _LIBCPP_NATIVE_PLATFORM_WAIT_SIZES(_APPLY) _APPLY(4)
+#endif
+
+#include_next <__atomic/atomic_waitable_traits.h>
+
+#endif  // OPENKAL_LIBCXX_ATOMIC_WAITABLE_TRAITS_OVERLAY

port/include/__atomic/contention_t.h

@@ -0,0 +1,57 @@
+// The width `std::atomic`'s contention counter has — which is the width the
+// platform's wait primitive takes, and openkal's is four bytes.
+//
+// ⭐ THE SAME QUESTION AS EVERY OTHER OVERLAY HERE, AND IT IS THE ONE THAT
+// DECIDES WHICH `__platform_wait_on_address<N>` GETS INSTANTIATED.
+//
+// Upstream picks by operating system — `int32_t` on Linux, `int64_t` on Apple,
+// FreeBSD and Windows — because each of those has a wait primitive of that
+// width. It is not a taste: `atomic.cpp` instantiates the templates at
+// `sizeof(__cxx_contention_t)` and the platform block `static_assert`s the size
+// it can serve.
+//
+// openkal's is `kal_task_wait(const kal_u32*, kal_u32, kal_u64)` — four bytes,
+// on every target, because that is what the specification says the suspension
+// primitive takes. So the answer here follows the C library, exactly as the
+// locale backend and the CRT selection do.
+//
+// ⚠️ Measured 2026-08-23, after `atomic.cpp`'s platform block was replaced but
+// before this file existed:
+//
+//     static assertion failed due to requirement '8UL == 4':
+//         Can only wait on 4 bytes value
+//
+// — the host build passed and the other two targets did not, because on Linux
+// upstream had already chosen four and elsewhere it had chosen eight. The
+// failure named the assertion rather than the type that produced the eight.
+//
+// ⚠️ AND THIS IS AN ABI DECISION. `__cxx_contention_t` appears in the mangled
+// names of the four exported entry points, so a program and a libc++ that
+// disagree about it do not link. That is the right failure — and it is why this
+// belongs in a header both sides read rather than in a flag one side passes.
+#ifndef OPENKAL_LIBCXX_CONTENTION_T_OVERLAY
+#define OPENKAL_LIBCXX_CONTENTION_T_OVERLAY
+
+#include <__config>
+
+// ⚠️ THE CONDITION IS THE C LIBRARY ALONE. It used to also require
+// `_LIBCPP_ABI_ATOMIC_WAIT_NATIVE_BY_SIZE`, mirroring upstream's own structure
+// — and measured, the overlay was reached and took the other branch, because
+// that macro is not defined at the point this header is first pulled in. The
+// fact this file states is true either way: openkal's wait primitive is four
+// bytes wide whether or not the ABI selects per size.
+#if _LIBCPP_HAS_MUSL_LIBC
+
+#  include <__atomic/support.h>
+#  include <cstdint>
+
+_LIBCPP_BEGIN_NAMESPACE_STD
+using __cxx_contention_t _LIBCPP_NODEBUG   = int32_t;
+using __cxx_atomic_contention_t _LIBCPP_NODEBUG = __cxx_atomic_impl<__cxx_contention_t>;
+_LIBCPP_END_NAMESPACE_STD
+
+#else
+#  include_next <__atomic/contention_t.h>
+#endif
+
+#endif  // OPENKAL_LIBCXX_CONTENTION_T_OVERLAY