.TH MCPU-RUN 1 "Октябрь 2026" "LibMCPU" "Команды пользователя" .SH ИМЯ mcpu-run \- загрузчик, runtime и supervisor исполнения MCPU .SH СИНТАКСИС .B mcpu-run .RI [ runtime-options ] " -- executable " [ program-args ...] .br .B mcpu-run .RI [ runtime-options ] " executable " [ program-args ...] .SH ОПИСАНИЕ .B mcpu-run — loader, startup linker, execution supervisor и host-side test bench для MELF ET_EXEC. Предпочтительна форма с явным разделителем .BR -- . Размеры STACK и HEAP являются частью executable ABI и не переопределяются runner-ом. .PP Поддерживаются статический ABI v1, исторический explicit-preload ABI v2 и frozen ABI v3. Discovery зависимостей, symbol selection и runtime relocation завершаются до первой guest instruction. .SH HLL STARTUP И LIFECYCLE HLL PROGRAM или MODEL executable всё равно входит через обычный MELF _start/_life/_fini lifecycle, предоставленный linked CRT. mcpu-run не вызывает main, init, life или fini напрямую. .PP Перед _start loader один раз создаёт в STACK постоянную область McpuStartup v1 с version, size, argc, PTR64 argv и reserved zero field. Массив argv и строки аргументов остаются действительными весь executable lifetime. HLL CRT проверяет это состояние и переводит его в обычный CALL ABI. .PP PROGRAM выполняет HLL main один раз и завершает работу с возвращённым int32 status. MODEL выполняет INIT через init(), затем вызывает life() один раз на каждой lifecycle iteration. INT32_MIN означает продолжение через одну LIFE END boundary; zero — нормальное завершение; positive value — error exit status. Остальные отрицательные результаты life зарезервированы HLL Runtime ABI v1. .PP Graceful HLL exit вызывает user fini(), __mcpu_fini_array() и __mcpu_libc_fini() перед финальным FINI END. Startup failure до перехода CRT в RUNNING пропускает эти finalizers. Diagnostic stop по --steps остаётся supervisor stop и не синтезирует graceful HLL finalization. .SH SYSTEM OPTIONS .TP .B --no-config Не читать mcpu-ld.conf, сохраняя executable-derived default system library tree. .TP .BI --sys-root= ПУТЬ Использовать ПУТЬ как MCPU root, не читать config и использовать ПУТЬ/lib. .TP .B --dump-config Вывести effective configuration и завершиться. .TP .B --print-search-dirs Вывести search directories и завершиться. .SH LIBRARY OPTIONS Эти опции должны находиться перед executable или явным --. .TP .BI --library-path= КАТАЛОГ[:КАТАЛОГ...] Добавить явные каталоги поиска. Опция повторяемая; эти каталоги предшествуют system library path. .TP .BI --ldpreload= a.so:b.so Предзагрузить ABI-v2/ABI-v3 shared objects. Имя без '/' ищется по search path; имя с '/' считается явным pathname. .SH ОКРУЖЕНИЕ .TP .B MCPU_LD_PRELOAD Colon-separated preload list, применяемый раньше command-line --ldpreload. При равной силе определения действует rightmost priority, поэтому command-line preload может переопределить environment preload. .SH INSPECTION ПОСЛЕ ОСТАНОВА .TP .BI --int-reg= r@ Вывести signed integer register. .TP .BI --real-reg= r@ Вывести real register. .TP .BI --int-data= @ .TQ .BI --real-data= @ .TQ .BI --raw-data= @ Inspection DATA. .TP .BI --int-control= @ .TQ .BI --real-control= @ .TQ .BI --raw-control= @ Inspection CONTROL. .TP .BI --int-heap= @ .TQ .BI --real-heap= @ .TQ .BI --raw-heap= @ Inspection HEAP. .TP .BI --int-input= @ .TQ .BI --real-input= @ .TQ .BI --raw-input= @ Inspection INPUT. .TP .BI --int-output= @ .TQ .BI --real-output= @ .TQ .BI --raw-output= @ Inspection OUTPUT. .TP .BI --int-trace= @ .TQ .BI --real-trace= @ .TQ .BI --raw-trace= @ Inspection TRACE. .SH LIFECYCLE CONTROL .TP .BI --digits= n Mantissa digits для real output; default 80. .TP .B --init-only Выполнить INIT до END и остановиться. .TP .BI --steps= n Остановиться после n LIFE END boundaries. .TP .BR -h ", " --help Вывести справку. .TP .B --version Вывести имя программы, идентификатор инструментария MCPU и версию, затем завершить работу. .TP .B --dump-version Вывести только номер версии пакета MCPU и завершить работу. .SH STAGE ACTIONS Повторяемые stage options выполняют host actions на lifecycle boundaries: .TP .BI --before-run= action После load/startup-link/relocations/startup area, до первой guest instruction. .TP .BI --after-init= action После INIT END или один раз на logical empty INIT boundary без .init. .TP .BI --on-step= action После каждого LIFE END. .TP .BI --after-run= action После final normal stop; graceful FINI уже завершён. .PP Формы actions: .nf print-int-regs:r@[,...] print-real-regs:r@[,...] set-int-regs:r@=[,...] set-real-regs:r@=[,...] print-int-:@[,...] print-real-:@[,...] set-int-:@=[,...] set-real-:@=[,...] print-raw-:@ .fi .PP memory = data, control, heap, input, output или trace. Scalar print выводит comma-list одной строкой. Raw action содержит ровно один dump; для нескольких нужно повторить stage option. set-raw-* отсутствуют. Set values разбираются LibMPUIO mpu_sscanf(). Step-number filters не реализованы. .SH LIFECYCLE И EXIT END возвращает управление supervisor-у на INIT/LIFE/FINI boundaries. Graceful EXIT может запустить optional FINI. Diagnostic stop по --steps не синтезирует EXIT и сам по себе FINI не запускает. .SH ФАЙЛЫ .TP .I /etc/mcpu-ld.conf Installed relocatable-tree configuration. .TP .I /etc/mcpu/mcpu-ld.conf Machine-wide override. .TP .I $HOME/.mcpu/etc/mcpu-ld.conf User override. .SH СТАТУС ЗАВЕРШЕНИЯ При нормальном завершении возвращается guest exit status. Loader/startup-linker, option и runtime errors дают ненулевой host-side status. .SH ПРИМЕРЫ .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 СМ. ТАКЖЕ .BR mcpu-ld (1), .BR mcpu-readelf (1), .BR mcpu-objdump (1), .BR libmcpu (7)