diff options
Diffstat (limited to 'man/mcpu-run.1')
| -rw-r--r-- | man/mcpu-run.1 | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/man/mcpu-run.1 b/man/mcpu-run.1 new file mode 100644 index 0000000..65c8f42 --- /dev/null +++ b/man/mcpu-run.1 @@ -0,0 +1,210 @@ +.TH MCPU-RUN 1 "October 2026" "LibMCPU" "User Commands" + +.SH NAME +mcpu-run \- load and execute an MCPU MELF executable +.SH SYNOPSIS +.B mcpu-run +.RI [ runtime-options ] " -- executable " [ program-args ...] +.br +.B mcpu-run +.RI [ runtime-options ] " executable " [ program-args ...] +.SH DESCRIPTION +.B mcpu-run +is the LibMCPU loader, startup linker, execution supervisor and host-side test +bench for MELF ET_EXEC images. The form with an explicit +.B -- +separator is preferred. STACK and HEAP sizes are part of the executable MELF +ABI and cannot be overridden by the runner. +.PP +The loader accepts static ABI-v1 executables, historical ABI-v2 explicit +preload files, and frozen ABI-v3 startup-dynamic executables and dependencies. +All startup dependency discovery, symbol selection and runtime relocation is +completed before the first guest instruction. +.SH HLL STARTUP AND LIFECYCLE +An HLL PROGRAM or MODEL executable still enters through the ordinary MELF +_start/_life/_fini lifecycle supplied by the linked CRT. mcpu-run does not +call main, init, life or fini directly. +.PP +Before _start, the loader constructs one persistent McpuStartup v1 area in +STACK containing version, size, argc, PTR64 argv and a reserved zero field. +The argv array and argument strings remain valid for the executable lifetime. +The HLL CRT validates this state and bridges it to the ordinary CALL ABI. +.PP +PROGRAM executes its HLL main once and exits with the returned int32 status. +MODEL performs INIT through init(), then invokes life() once per lifecycle +iteration. INT32_MIN means continue through one LIFE END boundary; zero means +normal completion; a positive value is an error exit status. Other negative +life results are reserved by HLL Runtime ABI v1. +.PP +Graceful HLL exit runs user fini(), __mcpu_fini_array() and +__mcpu_libc_fini() before the final FINI END. Startup failure before the CRT +reaches RUNNING skips those finalizers. A diagnostic --steps stop remains a +supervisor stop and does not synthesize graceful HLL finalization. +.SH SYSTEM OPTIONS +.TP +.B --no-config +Do not read mcpu-ld.conf files while keeping the executable-derived default +system library tree. +.TP +.BI --sys-root= PATH +Use PATH as the MCPU root, suppress configuration files and use PATH/lib as the +system library directory. +.TP +.B --dump-config +Print effective MCPU configuration and exit. +.TP +.B --print-search-dirs +Print effective library search directories and exit. +.SH LIBRARY OPTIONS +These options must precede the executable or explicit -- separator. +.TP +.BI --library-path= DIR[:DIR...] +Add explicit library search directories. The option may be repeated. These +directories precede the effective system library path. +.TP +.BI --ldpreload= a.so:b.so +Preload ABI-v2 or ABI-v3 shared objects. A name without slash is searched; +a spelling containing slash is used as an explicit pathname. +.SH ENVIRONMENT +.TP +.B MCPU_LD_PRELOAD +Colon-separated preload list applied before command-line --ldpreload entries. +For equal-strength definitions the established rightmost priority applies, so +command-line preloads can override environment preloads. +.SH POST-STOP INSPECTION OPTIONS +.TP +.BI --int-reg= r<bits>@<addr> +Print a signed integer register after execution stops. +.TP +.BI --real-reg= r<bits>@<addr> +Print a real register after execution stops. +.TP +.BI --int-data= <bits>@<addr> +.TQ +.BI --real-data= <bits>@<addr> +.TQ +.BI --raw-data= <bytes>@<addr> +Inspect DATA. +.TP +.BI --int-control= <bits>@<addr> +.TQ +.BI --real-control= <bits>@<addr> +.TQ +.BI --raw-control= <bytes>@<addr> +Inspect CONTROL. +.TP +.BI --int-heap= <bits>@<addr> +.TQ +.BI --real-heap= <bits>@<addr> +.TQ +.BI --raw-heap= <bytes>@<addr> +Inspect HEAP. +.TP +.BI --int-input= <bits>@<addr> +.TQ +.BI --real-input= <bits>@<addr> +.TQ +.BI --raw-input= <bytes>@<addr> +Inspect INPUT. +.TP +.BI --int-output= <bits>@<addr> +.TQ +.BI --real-output= <bits>@<addr> +.TQ +.BI --raw-output= <bytes>@<addr> +Inspect OUTPUT. +.TP +.BI --int-trace= <bits>@<addr> +.TQ +.BI --real-trace= <bits>@<addr> +.TQ +.BI --raw-trace= <bytes>@<addr> +Inspect TRACE. +.SH LIFECYCLE CONTROL +.TP +.BI --digits= n +Set mantissa digits for real output. Default: 80. +.TP +.B --init-only +Execute INIT through its END boundary, then stop. +.TP +.BI --steps= n +Stop after n LIFE END boundaries. Without this option normal diagnostic +stepping stops at the first LIFE END boundary. +.TP +.BR -h ", " --help +Display command-line help and exit. +.TP +.B --version +Display the program name, MCPU toolchain identity and version, then exit. +.TP +.B --dump-version +Display only the MCPU package version number and exit. +.SH STAGE ACTIONS +The following repeatable options run host actions at lifecycle boundaries: +.TP +.BI --before-run= action +After loading, startup linking, relocations and startup-area preparation, but +before the first guest instruction. +.TP +.BI --after-init= action +After INIT END, or once at the logical empty INIT boundary when .init is absent. +.TP +.BI --on-step= action +After every LIFE END boundary. +.TP +.BI --after-run= action +After final normal execution stop; graceful FINI has already completed. +.PP +Actions execute in command-line order. Supported action forms are: +.nf +print-int-regs:r<bits>@<addr>[,...] +print-real-regs:r<bits>@<addr>[,...] +set-int-regs:r<bits>@<addr>=<value>[,...] +set-real-regs:r<bits>@<addr>=<value>[,...] +print-int-<memory>:<bits>@<addr>[,...] +print-real-<memory>:<bits>@<addr>[,...] +set-int-<memory>:<bits>@<addr>=<value>[,...] +set-real-<memory>:<bits>@<addr>=<value>[,...] +print-raw-<memory>:<bytes>@<addr> +.fi +.PP +.I memory +is data, control, heap, input, output or trace. Scalar print actions print the +comma-separated objects on one line. Raw actions contain exactly one dump; +repeat the stage option for multiple dumps. There are no set-raw-* actions. +Set values are parsed by LibMPUIO mpu_sscanf(). Step-number action filters are +not implemented. +.PP +Raw byte counts accept K/KiB, M/MiB and G/GiB binary suffixes. +.SH LIFECYCLE AND EXIT +END returns control to the supervisor at managed INIT/LIFE/FINI boundaries. +A graceful guest EXIT may enter optional FINI before the final stop. A +diagnostic --steps stop does not synthesize a graceful EXIT and therefore does +not by itself invoke FINI. +.SH FILES +.TP +.I <runtime-root>/etc/mcpu-ld.conf +Installed relocatable-tree library-search configuration. +.TP +.I /etc/mcpu/mcpu-ld.conf +Optional machine-wide override. +.TP +.I $HOME/.mcpu/etc/mcpu-ld.conf +Optional per-user override. +.SH EXIT STATUS +For a normally completed guest program the runner returns the guest exit +status. Loader, startup-linker, option or runtime errors terminate with a +nonzero host-side status. +.SH EXAMPLES +.nf +mcpu-run -- program arg1 arg2 +mcpu-run --library-path=./lib -- program +MCPU_LD_PRELOAD=libhook.so mcpu-run -- program +mcpu-run --steps=20 --on-step=print-real-trace:128@0,128@16 -- pendulum +.fi +.SH SEE ALSO +.BR mcpu-ld (1), +.BR mcpu-readelf (1), +.BR mcpu-objdump (1), +.BR libmcpu (7) |