[GH-ISSUE #1255] docs(ghidra): clarify supported heap and CPU controls #452

New issue

Closed

opened 2026-10-15 18:25:11 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:25:11 +00:00

Owner

Originally created by @N0zoM1z0 on GitHub (Oct 9, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/1255

Current documentation gap

The working log's unsupported custom JVM flags and RSS expectations are easy to repeat. REA already consumes GHIDRA_HEADLESS_MAXMEM; this is not a missing heap-control feature. General Ghidra setup/configuration should explain supported controls and the settings the launcher intentionally replaces.

Source-confirmed behavior on current main

POSIX direct launch uses GHIDRA_HEADLESS_MAXMEM, then GHIDRA_MAXMEM, then a 2G heap default. The audited real sessions used the supported 512 MiB heap setting.
Generic/custom JVM injection variables are cleared. The launcher owns GHIDRA_HEADLESS_JAVA_OPTIONS; callers must not claim their custom flags reached the JVM without verifying the actual process.
The direct launch fixes GC/compiler thread counts, but this does not bound all JVM activity. Headless arguments do not expose -max-cpu, and caller CPU affinity remains an external execution constraint.
Heap, Node heap and sampled total process-family RSS are different measurements. Resource settings affect cost/latency and are not currently part of semantic target/profile identity.

docs/testing.md mentions small-host heap/affinity guidance inside a specialized NativeAOT lane. The basic provider setup workflow lacks the same prominent explanation.

Desired outcome

Document supported heap settings, intentional environment overrides, CPU-affinity guidance and the absence of a general configured CPU limit in the provider setup/resource guide. Provide actionable diagnostics where available and point to actual supported configuration, without inventing a new ignored option. Show how to verify settings reached their consumer. Avoid presenting fixed GC threads or heap as a whole-process CPU/RSS bound.

No installer should install/upgrade Ghidra, Java or unrelated software. A separately configurable Ghidra CPU policy would require its own verified consumer and is not required merely to correct this documentation.

Evidence and relationship

Source-only documentation/configuration audit, plus successful latest-version native runs using the supported heap setting. No CPU-scaling benchmark or JVM-wide RSS claim was made. Related #1048 and #1065.

Sources: GhidraJavaLaunch.ts:76, GhidraInstallation.ts:425, GhidraLauncher.ts:313, docs/testing.md:511.

Audit date 2026-10-09; latest npm release verified as 6.1.0 and source main pinned at f4c99ab8a53806dd57dc24b3d5a600905bcb4686. Linux x64, Node 24.18.0, Ghidra 12.1.4 and JDK 21. Other host launch paths were source-inspected, not independently runtime-verified in this batch.

Originally created by @N0zoM1z0 on GitHub (Oct 9, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/1255 ### Current documentation gap The working log's unsupported custom JVM flags and RSS expectations are easy to repeat. REA already consumes `GHIDRA_HEADLESS_MAXMEM`; this is not a missing heap-control feature. General Ghidra setup/configuration should explain supported controls and the settings the launcher intentionally replaces. ### Source-confirmed behavior on current main - POSIX direct launch uses `GHIDRA_HEADLESS_MAXMEM`, then `GHIDRA_MAXMEM`, then a 2G heap default. The audited real sessions used the supported 512 MiB heap setting. - Generic/custom JVM injection variables are cleared. The launcher owns `GHIDRA_HEADLESS_JAVA_OPTIONS`; callers must not claim their custom flags reached the JVM without verifying the actual process. - The direct launch fixes GC/compiler thread counts, but this does not bound all JVM activity. Headless arguments do not expose `-max-cpu`, and caller CPU affinity remains an external execution constraint. - Heap, Node heap and sampled total process-family RSS are different measurements. Resource settings affect cost/latency and are not currently part of semantic target/profile identity. `docs/testing.md` mentions small-host heap/affinity guidance inside a specialized NativeAOT lane. The basic provider setup workflow lacks the same prominent explanation. ### Desired outcome Document supported heap settings, intentional environment overrides, CPU-affinity guidance and the absence of a general configured CPU limit in the provider setup/resource guide. Provide actionable diagnostics where available and point to actual supported configuration, without inventing a new ignored option. Show how to verify settings reached their consumer. Avoid presenting fixed GC threads or heap as a whole-process CPU/RSS bound. No installer should install/upgrade Ghidra, Java or unrelated software. A separately configurable Ghidra CPU policy would require its own verified consumer and is not required merely to correct this documentation. ### Evidence and relationship Source-only documentation/configuration audit, plus successful latest-version native runs using the supported heap setting. No CPU-scaling benchmark or JVM-wide RSS claim was made. Related #1048 and #1065. Sources: [GhidraJavaLaunch.ts:76](https://github.com/morluto/rea/blob/f4c99ab8a53806dd57dc24b3d5a600905bcb4686/src/ghidra/GhidraJavaLaunch.ts#L76), [GhidraInstallation.ts:425](https://github.com/morluto/rea/blob/f4c99ab8a53806dd57dc24b3d5a600905bcb4686/src/ghidra/GhidraInstallation.ts#L425), [GhidraLauncher.ts:313](https://github.com/morluto/rea/blob/f4c99ab8a53806dd57dc24b3d5a600905bcb4686/src/ghidra/GhidraLauncher.ts#L313), [docs/testing.md:511](https://github.com/morluto/rea/blob/f4c99ab8a53806dd57dc24b3d5a600905bcb4686/docs/testing.md#L511). Audit date 2026-10-09; latest npm release verified as 6.1.0 and source main pinned at `f4c99ab8a53806dd57dc24b3d5a600905bcb4686`. Linux x64, Node 24.18.0, Ghidra 12.1.4 and JDK 21. Other host launch paths were source-inspected, not independently runtime-verified in this batch.

bsakaguchi

2026-10-15 18:25:11 +00:00