Troubleshooting

Troubleshooting and problem isolation

For common missing-library, binfmt, AVX, floating-point, TSO, or page-size issues, start with the FAQ. Before changing configuration or source, ordinary users should first:

1. save the LATX version, host details, guest file type, complete command, and error output;
2. use the static-program check in Build, installation, and runtime to distinguish a translator issue from a runtime issue, and use -runtime-info to confirm the guest runtime;
3. change one runtime option at a time; current semantics and defaults are in Configuration and environment variables.

This page describes how to systematically locate functional and compatibility problems when using the LAT binary translator. It focuses on version comparison, LAT-TCG/QEMU-TCG comparison, TSO settings, page-size changes, and runtime alignment to determine whether a problem is caused by:

• a false positive from environmental factors such as missing guest runtime dependencies under /usr/gnemul;
• an LAT instruction-translation error;
• a missing upstream QEMU linux-user backport; or
• a bug in another LAT component.

The aim is to find the real owner of a LAT issue by the shortest path.

---

1. Basic debugging principles

When locating a problem, follow these principles:

1. Rule out environment issues before investigating the translator.
2. First check whether adjusting relevant LAT environment variables changes the behavior.
3. First determine whether it is a version regression, then investigate the specific code defect.
4. For particular guest software, check the recommended memory-ordering setup.
5. For particular errors such as SIGSEGV, use a different system page size as a compatibility check.
6. Compare with other translators such as LAT-TCG and QEMU-TCG to validate instruction semantics and correctness.
7. ABI 1.0 (old world) and ABI 2.0 (new world) use different implementations in some code guarded by CONFIG_LOONGARCH_NEW_WORLD; test the other ABI to see whether that implementation difference is involved.
8. If these steps do not identify the issue, investigate it directly.

2. Basic LAT problem-isolation steps

These steps are suggestions rather than a strict sequence.

2.1 Try a different translator version

Although the first principle is to rule out environment issues, replacing the translator is usually inexpensive. Test translators from different tags to see whether the problem is:

• a long-standing issue; or
• a regression introduced in a particular version.

2.1.1 How to switch translators

You can replace the translator in /usr/bin/, but that can create package manager risks. Alternatively, temporarily change the binfmt path to point to the translator under test.

2.1.2 Continue after confirming a regression

For a newly introduced regression, use Git bisection:

git bisect start
git bisect bad commit-id
git bisect good commit-id

Build and test iteratively to identify the introducing commit.

2.2 Adjust LAT environment variables

Current option semantics, defaults, and configuration precedence are maintained in Configuration and environment variables. Use one-shot environment variables for comparison and change one option at a time, for example:

LATX_AOT=0 latx-x86_64 /path/to/program
LATX_SOFTFPU=1 latx-x86_64 /path/to/program
LATX_ANONYM=1 latx-x86_64 /path/to/program

Write the option to a guest-specific configuration section only after confirming that it has the intended effect.

2.3 Rule out environment problems

For large closed-source programs, you can run a guest-architecture Docker environment through LAT to get the program running first. This can determine which libraries the program needs and whether they exist in the guest runtime under /usr/gnemul.

Use latx-x86_64 -runtime-info or latx-i386 -runtime-info to confirm the runtime directory LATX actually selected. If a static program works but a dynamically linked program fails, check the dynamic linker and shared libraries in that directory first.

2.4 Enable TSO for .NET or Java guest programs

See memory-model-config for the procedure.

2.5 Try a 4K-page kernel

For some SIGSEGV errors, try a 4K-page kernel. For example, if si_code is 2 and the corresponding siaddr has the expected permission in the guest, the 4K/16K shadow-page compatibility mechanism may be involved.

2.6 Compare LAT-TCG and QEMU-TCG

Comparing with LAT-TCG can show whether an instruction translation is wrong. LAT does not ensure that every upstream QEMU linux-user patch is backported, so compare with QEMU-TCG as well to see whether backporting an upstream patch could resolve the issue.

2.7 Compare old-world and new-world behavior

For ABI 1.0 (old world) and ABI 2.0 (new world), LAT uses different implementations in some code guarded by CONFIG_LOONGARCH_NEW_WORLD. Test the other ABI to determine whether that implementation difference is involved.

---

3. Some LAT debugging approaches

If the preceding experiments still cannot run the program, begin direct debugging.

3.1 Disable more optimizations

Besides AOT and library pass-through, LAT has other optimizations that can be disabled. optimize-config.h has common build-time switches; for example, comment out the following lines to disable flag-reduction optimization:

#undef CONFIG_LATX_FLAG_REDUCTION
#define CONFIG_LATX_FLAG_REDUCTION  /* flag reduction */

3.2 SIGSEGV and other exits with an obvious cause

For these cases, inspect information in the signal context. As in QEMU, LAT's first signal entry point is host_signal_handler(), which is a useful place to start the analysis.

3.3 strace

Capture an strace log for the translated run and compare it with a log from a native-architecture run to identify obvious errors.

---

Document version: v1.0

Intended audience: anyone beginning to debug LAT

Maintainer: Hanlu Li heuleehanlu@gmail.com