FAQ

Frequently asked questions

How do I confirm that LATX is usable after installation?

First confirm that both translators are present and executable:

latu-runtime-manager status

The output should include:

translator_x86_64=present
translator_i386=present

For the first run, use a statically linked program so that a missing guest runtime is not mistaken for a translator failure. Build, installation, and runtime provides a BusyBox validation command.

LATX works when invoked explicitly, but executing an x86 program directly fails. What should I do?

This usually means binfmt has not been loaded. After installing the tar package, restart the system or, on a systemd system, run:

sudo systemctl restart systemd-binfmt.service
systemctl status systemd-binfmt.service

If the translator is not in /usr/bin, also update the path in /usr/lib/binfmt.d/latx-*.conf.

Why does a dynamically linked program report a missing interpreter or shared library?

A static program needs only the translator. A dynamically linked program also needs a guest runtime containing the x86 dynamic linker and shared libraries. First check its architecture and linking mode:

file /path/to/program
readelf -l /path/to/program | grep interpreter

Then inspect the runtime selected by LATX:

latx-x86_64 -runtime-info
latx-i386 -runtime-info

The reported runtime_root must contain the interpreter and libraries required by the program. See Build, installation, and runtime for installation. To test another root temporarily, use LAT_LD_PREFIX=/path/to/root or -L /path/to/root.

Why do ABI 1.0 and ABI 2.0 use different runtime paths?

LATX detects the host ABI at build time and writes the corresponding default paths:

Host ABI	i386	x86_64
ABI 1.0	/usr/gnemul/latx-i386	/usr/gnemul/latx-x86_64
ABI 2.0	/usr/gnemul/lat-i386	/usr/gnemul/lat-x86_64

Build in an environment matching the target ABI. Check the actual selected path with -runtime-info rather than inferring it from a directory name.

What if my program needs AVX?

Both build32.sh and build64.sh accept -a:

./latxbuild/build32.sh -c -a
./latxbuild/build64.sh -c -a

-a passes --enable-latx-avx-opt at configuration time, enabling x86 AVX instruction translation for the selected build target. Include -c whenever you change AVX support so that the build configuration is regenerated. An AVX build reports the relevant CPUID features by default. LATX_AVX_CPUID=0 changes that AVX-related CPUID reporting; it does not disable compiled AVX translation and cannot be changed while the guest is running.

What if a .NET or Java program has a concurrency or memory-ordering problem?

First follow memory-model-config to check and configure TSO, then determine whether the issue is in LATX translation. Record the configuration and observed behavior before and after the change so that a host memory-model difference is not mistaken for a guest program defect.

What if a program detects a virtualized environment and refuses to run?

For one invocation, try:

LATX_ANONYM=1 latx-x86_64 /path/to/program

This option hides some LATX characteristics and automatically disables AOT. It affects only this process. If it works, add it to the relevant guest section as described in Configuration and environment variables.

What if floating-point results or precision are incorrect?

Keep a reproducible input and the original result, then try software floating point:

LATX_SOFTFPU=1 latx-x86_64 /path/to/program

Software floating point disables AOT and rounding optimization and normally reduces performance. It is useful for diagnosis or as a compatibility workaround, but it does not replace a minimal reproducer.

How should I investigate SIGSEGV with si_code=2?

First confirm that the guest mapping should have the relevant permission and record the host page size:

getconf PAGESIZE

If it occurs only with a 16K-page kernel, reproduce it on a 4K-page kernel to determine whether the 4K/16K shadow-page compatibility path is involved. This is an attribution step; it does not mean that every SIGSEGV is a page-size issue. Continue with Troubleshooting to compare versions, runtime, LAT-TCG, and QEMU-TCG.

What should I include in a report that maintainers can act on?

When opening an Issue, include at least:

• the LATX version or commit;
• host distribution, LoongArch ABI, uname -a, and getconf PAGESIZE;
• file output for the guest and whether it is static or dynamically linked;
• latx-x86_64 -runtime-info or latx-i386 -runtime-info output;
• the complete command, environment, error output, and reliable reproduction steps;
• whether it reproduces with other LATX versions, LAT-TCG, QEMU-TCG, or native x86.

Do not provide screenshots alone: searchable, copyable text logs are much more useful for diagnosis.