path: root/man/mcpu-run.1

.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)