fix: flush CPU cache lines in device UUID header read/write paths

[seohui-XCENA]

🤔 Background & Motivation (Why)

• The device UUID header is read/written with plain CPU load/store through a DEV_DAX mmap. CPU stores stay in the write-back cache, and msync() does not flush CPU caches on DEV_DAX (no page cache, no fsync op).
• CXL 2.x shared memory has no cross-host cache coherence, so on multi-host setups a freshly written header is invisible to other hosts — both RMs auto-initialize the same device with different UUIDs (identity split-brain) — and a header cached by an earlier read goes stale when another host rewrites it.
• Multi-host simulation (HDM window aliasing) measured the CPU-store path stale 0/50 on every platform, corrected only by clflush+fence.

🏗️ Design Changes

• Behavioral: header writes now end with clflush+mfence (write-back to device), header reads now start with clflush+mfence (invalidate any stale local copy). Encapsulated inside the header R/W functions — no caller changes.
• Dependency: new optional C extension maru_shm._cxl_flush; if not built, Python falls back to a no-op with a one-time warning (single-host behavior unchanged).

sequenceDiagram
    participant A as Host A (RM / CLI)
    participant C as Host A CPU cache
    participant D as CXL device
    participant B as Host B (scanner)

    rect rgb(255, 235, 235)
    Note over A,B: Before — header trapped in Host A's cache
    A->>C: store header (mmap memcpy)
    C--xD: write-back deferred indefinitely (msync = no-op on DEV_DAX)
    B->>D: read header
    D-->>B: zeros → "no header" → B re-inits with a different UUID (split-brain)
    end

    rect rgb(235, 255, 235)
    Note over A,B: After — explicit cache-line flush
    A->>C: store header (mmap memcpy)
    A->>C: clflush + mfence
    C->>D: header line written back
    B->>B: clflush (drop stale local copy)
    B->>D: read header
    D-->>B: valid magic + UUID
    end

Loading

📝 Implementation Details

• maru_resource_manager/src/device_header.cpp: flushCacheRange() (clflush per 64B line + mfence; x86-only, no-op elsewhere) — called after the store in writeDeviceHeader() and before the load in readDeviceHeader(). msync kept as best effort for regular-file backing (tests).
• maru_shm/_cxl_flush.c (new): flush_range(buffer, offset=0, length=-1) via buffer protocol with bounds checking; HAVE_CLFLUSH constant. Registered in setup.py as an optional extension.
• maru_shm/device_scanner.py: flush applied in write_device_header / clear_device_header (after store) and read_device_uuid (before load). mm.flush() wrapped in try/except — DEV_DAX may reject msync with EINVAL.

✅ Tests

• Unit tests — 10 new in tests/unit/test_device_scanner.py (extension-missing fallback roundtrip, one-time warning, msync error swallow, flush_range bounds); C++ maru_rm_tests 16/16
• Integration tests — tests/integration/test_daxmapping_flow.py passes
• Manual tests — cross-host visibility verified on the multi-host window-alias harness: control 50/50, aliased writer 50/50 / reader 50/50, RM auto-init header identical through both windows

🔗 Related Issues (optional)

📦 Release Note (for auto-generation / write in English)

NEW

CHANGED

FIXED

• RM: Device UUID header reads/writes now flush CPU cache lines so the header is visible and fresh across hosts sharing a CXL device (multi-host UUID resolution).

IMPORTANT NOTES

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
__init__.py	6	0	100%
__main__.py	3	3	0%	5, 7–8
allocation_manager.py	129	11	91%	30–31, 44–45, 52, 237–238, 268–271
client.py	187	8	96%	88, 130, 147–148, 311–313, 319
config.py	46	1	98%	72
constants.py	9	0	100%
device_scanner.py	113	4	96%	12–13, 60, 93
handler.py	557	86	85%	153, 168, 179–186, 194–196, 211, 217–219, 227, 238–243, 248, 273, 300–301, 305, 345, 349–350, 355, 377, 384–385, 389–395, 398, 402–404, 420, 422–423, 432, 486, 507, 517–518, 624–626, 633, 755–758, 761, 772–775, 781, 867, 971, 1134–1138, 1144, 1155–1159, 1165, 1244, 1249, 1291
ipc.py	275	2	99%	365, 441
kv_manager.py	108	0	100%
logging_setup.py	19	0	100%
plugin.py	59	3	95%	65–67
protocol.py	233	0	100%
resource_manager_installer.py	103	13	87%	80–86, 167, 169–172, 187
rpc_async_client.py	190	0	100%
rpc_async_server.py	111	0	100%
rpc_client.py	71	0	100%
rpc_client_base.py	106	10	91%	185, 221–222, 233–234, 306–307, 311–312, 375
rpc_handler_mixin.py	106	19	82%	154–156, 159–161, 219–222, 227, 231–235, 256–257, 263
rpc_server.py	64	0	100%
serializer.py	81	0	100%
server.py	170	13	92%	64–65, 73, 168, 172, 243, 247, 265–266, 357–359, 444
stats_manager.py	95	0	100%
types.py	60	1	98%	145
uds_helpers.py	13	0	100%
memory
__init__.py	5	0	100%
allocator.py	55	0	100%
mapper.py	130	3	98%	229, 251, 300
owned_region_manager.py	101	1	99%	212
types.py	62	0	100%
TOTAL	3288	178	95%

Tests	Skipped	Failures	Errors	Time
717	4 💤	0 ❌	0 🔥	7.287s ⏱️

[jooho-XCENA]

로직·경계처리·에러처리 모두 정확해서 approve합니다. 요약과 minor 코멘트 몇 개 남깁니다.

정확성 확인

• x86 메모리 모델 관점에서 올바름: CLFLUSH는 같은 캐시라인에 대한 이전 store와 순서가 보장되므로 writer 쪽 store → clflush → mfence, reader 쪽 clflush → mfence → load 모두 정확합니다.
• 캐시라인 정렬 루프(addr & ~63 시작)가 경계 걸침을 올바르게 처리합니다.
• flush_range의 bounds check가 offset > len 케이스(음수 length로 환원)까지 잡고, y*가 read-only 버퍼(PROT_READ mmap)를 수용하므로 read 경로도 문제없습니다.
• msync를 best-effort로 강등한 것(DEV_DAX EINVAL)도 타당하며 회귀 위험 없습니다.
• 테스트 커버리지(fallback roundtrip, 1회 경고, msync swallow, bounds) 좋습니다.

Minor

1. 비-x86에서 경고 비대칭: ARM 등에서는 확장이 빌드되고 HAVE_CLFLUSH=0인데 flush_range가 조용히 no-op라서, _flush_range is None fallback 경고 경로를 타지 않아 경고가 전혀 안 나옵니다. device_scanner.py에서 _cxl_flush.HAVE_CLFLUSH == 0일 때도 같은 1회 경고를 내면 일관적입니다 (상수를 export해놓고 현재 사용처가 없음).
2. clflushopt 대신 clflush를 택한 이유(가용성 우선, 헤더 32B라 성능 무의미)를 주석 한 줄로 남기면 좋겠습니다.
3. 이 PR은 UUID 헤더만 flush합니다. RM 풀 메타데이터 등 다른 CPU-store 공유 구조가 같은 문제를 가질 수 있으니 후속 과제로 기록해두면 좋겠습니다.
4. Extension(optional=True)는 최신 setuptools에서 deprecation 논의가 있는 필드입니다. 지금은 동작하니 blocker 아님.

멀티호스트 window-alias 하드웨어 검증을 머지 전 필수 게이트로 볼지 여부만 합의하면 될 것 같습니다.

[seohui-XCENA]

Thanks for the thorough review!

• (1) Fixed in 81a0f6a — the one-time warning now also fires when the extension is built without clflush support (HAVE_CLFLUSH=0, non-x86), with a test.
• (2) Added the clflush-vs-clflushopt rationale as comments in both flush helpers (same commit).
• (3) Checked: the UUID header is currently the only CPU-store path to the CXL region — RM metadata (WAL/free list) lives on local disk and flows over TCP, and the KV data plane is GPU DMA only. Agreed it's worth watching whenever a new CPU-store path is added.
• (4) Agreed, leaving optional=True as is.

Re: the merge gate — hardware verification is done. On the multi-host window-alias setup: control 50/50; aliased windows writer 50/50, reader 50/50; and the RM auto-init header reads back identically through both windows (covers the C++ write-flush and read-invalidate paths as well as the Python ones).