Version 0.4.00.4.0

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)