Skip to content

LATU: add read-only runtime diagnostics - #381

Open
LaurenIsACoder wants to merge 6 commits into
lat-opensource:masterfrom
LaurenIsACoder:lauren/latu-runtime-query-pr4
Open

LATU: add read-only runtime diagnostics#381
LaurenIsACoder wants to merge 6 commits into
lat-opensource:masterfrom
LaurenIsACoder:lauren/latu-runtime-query-pr4

Conversation

@LaurenIsACoder

@LaurenIsACoder LaurenIsACoder commented Aug 10, 2026

Copy link
Copy Markdown
Contributor

Series

This is PR 4 in the LATU runtime usability series. Its prerequisites are
already merged into master:

Summary

  • replace the installed shell status helper with a native GLib-only
    latu-runtime-manager while preserving the existing two-line status contract
  • add current and list commands that query latx-x86_64 and latx-i386
    through their versioned --runtime-info interface
  • add inspect-root to validate canonical x86_64 and i386 ELF loaders without
    executing guest code
  • add doctor to diagnose the translator, selected runtime root, configured
    loader, and effective loader chain
  • let doctor --program derive the guest ABI and real PT_INTERP from the
    program rather than asking users to know those details
  • default ordinary queries and diagnosis to both ABIs, with --abi retained as
    an optional expert filter
  • emit newline-delimited JSON for automation and stable exit statuses for
    ready, broken, and unknown results

Examples:

$ latu-runtime-manager current
$ latu-runtime-manager inspect-root /opt/x86-runtime
$ latu-runtime-manager doctor
$ latu-runtime-manager doctor --program ./guest-program

The manager follows translator-reported configuration precedence instead of
parsing LATX configuration files itself. It bounds translator output to 1 MiB
and ten seconds, validates strict UTF-8 JSON, confines runtime-root symlink
resolution, and validates loader ELF metadata before reporting a root ready.

Distribution-neutral scope

The product implementation does not read os-release, branch on distribution
IDs, invoke distribution package managers, or contain a distribution allowlist.
AOSC, Debian, and Fedora names occur only in the GitHub Actions container matrix,
where the same generic lat-pr-fast suite exercises the same code in different
build environments.

This PR is intentionally read-only. It does not download, create, install,
update, or remove a runtime, and it does not modify translator configuration.
Those provisioning operations remain follow-up work.

Commit structure

  1. runtime: replace status script with native manager
  2. runtime: query selected guest runtimes
  3. runtime: inspect guest runtime roots
  4. runtime: diagnose loaders for guest programs
  5. tests: exercise diagnostics with real translators
  6. docs: describe read-only runtime diagnostics

Each behavioral slice carries its focused tests. Target-dependent tests are
registered through Meson and selected by the generic lat-pr-fast suite rather
than by manager-specific GitHub Actions steps.

Validation

The history cleanup changed only commit boundaries and messages. The final
tree object before and after cleanup is identical:
f4b0c70b5fb0fcfc82b00474a7854b82fca9a953.

On a physical LoongArch host, the pre-clean product tree before the portable
build-wiring follow-up passed:

  • incremental dual-target product build: passed
  • lat-pr-fast: 17/17 passed with x86_64 and i386 translators enabled
  • focused distribution-neutral manager query and diagnosis test: passed
  • tests-disabled product build: passed, with no tests registered or built
  • real built translators were queried through --runtime-info for both ABIs
  • git diff --check, workflow YAML parsing, shell syntax, DCO, and final-file
    checkpatch validation: passed
  • patch-series checkpatch: no errors; only the generic MAINTAINERS reminder for
    added files

The manager and translator product C sources in that native run are identical
to the cleaned final tree. This physical result does not claim validation of
the later build and CI wiring; that boundary is covered by GitHub Actions.

For the cleaned six-commit series:

  • final-tree git diff --check, shell syntax, workflow YAML parsing, and DCO:
    passed
  • per-commit checkpatch: no errors; only the generic MAINTAINERS reminder for
    commits that add or remove files
  • the native-manager build, release packaging, portable Meson invocation, and
    install validation are complete in the first commit; no later commit repairs
    those paths
  • GitHub Actions on cleaned HEAD cb63f58d1d8e: 22/22 checks passed
  • AOSC, Debian, and Fedora lat-pr-fast: 17/17 passed in each environment;
    the real-translator, install, and native-manager tests all passed
  • AOSC, Debian, and Fedora release builds and refreshed CI container builds:
    passed

The deterministic test runtime uses synthetic loader ELF files and skips guest
execution, so these results do not claim a real rootfs or translated guest E2E.

Checklist

  • I have read CONTRIBUTING.md.
  • Every commit contains a DCO sign-off.
  • I have included relevant build and test results.

@LaurenIsACoder
LaurenIsACoder force-pushed the lauren/latu-runtime-query-pr4 branch from be45ef6 to 72051b4 Compare August 10, 2026 08:07
Preserve the stable two-line status contract and rooted symlink checks
while replacing the installed shell helper with a native executable. The
manager links only GLib, so building it does not pull in qemuutil.

Install and package the compiled manager rather than the removed script.
Validate installation through Ninja so the build directory is never read
by a different Meson version.

Drive the generic dual-target lat-pr-fast matrix with one system Meson per
environment, and keep target-dependent install coverage in the top-level
Meson build.

Signed-off-by: Hanlu Li <heuleehanlu@gmail.com>
Add current and list commands backed by the versioned --runtime-info
interface of each translator. The manager preserves translator
configuration precedence instead of parsing LATX configuration itself.

Default queries cover x86_64 and i386, while --abi remains an optional
filter. A selected runtime is successful when the peer ABI is unavailable;
an unknown or failed peer still dominates with exit status 2.

Bound translator output to 1 MiB and ten seconds, parse strict UTF-8 JSON,
and cover failure and escaping cases.

Signed-off-by: Hanlu Li <heuleehanlu@gmail.com>
Add inspect-root for read-only validation of the canonical x86_64 and i386 loader paths. A valid loader must be a readable regular ELF of the expected class and machine with a loadable segment.

Resolve symlink chains without accepting paths that escape the inspected root, and report stable ready, missing, invalid, or unknown results with machine-readable exit statuses.

Signed-off-by: Hanlu Li <heuleehanlu@gmail.com>
Add doctor for the complete translator, runtime selection, and loader
chain. With --program, inspect the guest ELF to select its ABI and
PT_INTERP; static guests require no loader.

Report configured-root and effective loader status separately. Match LAT
lookup behavior by accepting an absolute host loader only when the
configured copy is absent, while an existing invalid configured loader
remains a failure.

When the requested program cannot be inspected, emit a complete unknown
NDJSON record with a stable program_reason before returning exit status 2.

Signed-off-by: Hanlu Li <heuleehanlu@gmail.com>
Register target-dependent diagnostics in the top-level Meson build and run them through the generic lat-pr-fast suite. The test invokes both built translators for runtime-info queries and manager orchestration.

Use synthetic loader ELF files and skip guest execution in nested CI, keeping the gate deterministic and independent of a preinstalled x86 rootfs.

Signed-off-by: Hanlu Li <heuleehanlu@gmail.com>
Document status, current, list, inspect-root, and doctor, including the default dual-ABI view and optional ABI filter.

Clarify the read-only boundary, structured output and exit statuses, program ELF handling, and the distinction between a self-contained runtime root and LAT host-loader fallback.

Signed-off-by: Hanlu Li <heuleehanlu@gmail.com>
@LaurenIsACoder
LaurenIsACoder force-pushed the lauren/latu-runtime-query-pr4 branch from 72051b4 to cb63f58 Compare August 10, 2026 09:14
@LaurenIsACoder
LaurenIsACoder marked this pull request as ready for review August 11, 2026 08:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant