Document trimmable JNI interoperability

[simonrozsival]

---

Pull Request
title and
description
should follow the
commit-messages.md workflow documentation, and in particular should include:

• Useful description of why the change is necessary.
• Links to issues fixed — N/A; this follows the runtime cleanup in Remove legacy native typemap runtime support #12890.
• Unit tests — not run (documentation-only change).

Summary

Replace the outdated JNI interoperability guide with a source-backed guide to the trimmable TypeMap used by CoreCLR and NativeAOT. The old text describes removed MonoVM/LLVM typemaps and native marshal registration; this guide instead explains generated JCWs and managed TypeMap assemblies, the Java-to-managed and managed-to-Java call paths (including possible virtual-dispatch round trips), JNI RegisterNatives, UTF-8 registration data, peer lifetime, trimming, and troubleshooting. Link it from the documentation index.

Validation

• Checked all 58 relative links in the guide and 23 in the documentation index: no missing targets.
• git diff --check: passed.

The PR now targets main after #12890 merged. No stack metadata was changed.

[Copilot]

Copilot review overview

🟡 Changes recommended

Resolve the outstanding documentation accuracy and terminology nits before approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 2

Open (2)

• Clarify virtual dispatch can round-trip through managed callbacks · New
• Use managed terminology for RegisterNatives troubleshooting · New

What changed in this PR

This documentation-only PR adds an internal guide for trimmable TypeMap JNI interoperability across CoreCLR and NativeAOT.

Changes:

• Adds detailed generation, registration, peer-lifetime, trimming, and troubleshooting guidance.
• Links the guide from the documentation index.

File	Summary
Documentation/​README.md	Adds the interoperability guide to the documentation index.
Documentation/​guides/​internals/​JavaJNI_Interop.md	Documents the trimmable TypeMap JNI pipeline; outstanding nits address callback naming, generator output passes, virtual dispatch, deferred registration, and managed RegisterNatives terminology.

[simonrozsival]

@dalexsoto review

[dalexsoto]

The two earlier virtual-dispatch and managed-registration troubleshooting concerns are fixed. Two independent current-path assertions still need correction in Documentation/guides/internals/JavaJNI_Interop.md:

1. Removed API described as compatible (line 127). Runtime.register does not remain a compatibility stub at this revision: src/java-runtime/java/mono/android/Runtime.java has only registerNatives(Class), and the old Java_mono_android_Runtime_register entrypoint is absent from both src/native/clr/host/host-jni.cc and src/native/clr/libnet-android.map.txt. An old caller cannot resolve the documented stub. Remove that compatibility promise or explicitly state that the old API was removed; restoring it is not requested.

2. Callback-frame ownership misdescribed (line 184). TypeMapAssemblyEmitter.EmitUcoForwarderBody (lines 1200-1228) emits a bridge wait and a catch that calls AndroidEnvironmentInternal.UnhandledException; it does not emit BeginMarshalMethod, OnUserUnhandledException, or an EndMarshalMethod finally region. Direct exports and constructor entrypoints do own that frame, and modern binding callbacks can establish it inside JniMarshal.SafeInvoke. Describe these protection routes separately so JNI-transition and exception debugging follows the actual layer. This is a documentation correction, not a claim that modern callbacks are unprotected.

Both changed files, the full replacement guide, and its seven material integration paths were inspected at the pinned revision; no additional high-confidence blocker remains in this static review.