Version 0.4.00.4.0

1 files changed, 199 insertions, 0 deletions

diff --git a/man/ru/mcpu-run.1 b/man/ru/mcpu-run.1
new file mode 100644
index 0000000..9701dcf
--- /dev/null
+++ b/man/ru/mcpu-run.1
@@ -0,0 +1,199 @@
+.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<bits>@<addr>
+Вывести signed integer register.
+.TP
+.BI --real-reg= r<bits>@<addr>
+Вывести real register.
+.TP
+.BI --int-data= <bits>@<addr>
+.TQ
+.BI --real-data= <bits>@<addr>
+.TQ
+.BI --raw-data= <bytes>@<addr>
+Inspection DATA.
+.TP
+.BI --int-control= <bits>@<addr>
+.TQ
+.BI --real-control= <bits>@<addr>
+.TQ
+.BI --raw-control= <bytes>@<addr>
+Inspection CONTROL.
+.TP
+.BI --int-heap= <bits>@<addr>
+.TQ
+.BI --real-heap= <bits>@<addr>
+.TQ
+.BI --raw-heap= <bytes>@<addr>
+Inspection HEAP.
+.TP
+.BI --int-input= <bits>@<addr>
+.TQ
+.BI --real-input= <bits>@<addr>
+.TQ
+.BI --raw-input= <bytes>@<addr>
+Inspection INPUT.
+.TP
+.BI --int-output= <bits>@<addr>
+.TQ
+.BI --real-output= <bits>@<addr>
+.TQ
+.BI --raw-output= <bytes>@<addr>
+Inspection OUTPUT.
+.TP
+.BI --int-trace= <bits>@<addr>
+.TQ
+.BI --real-trace= <bits>@<addr>
+.TQ
+.BI --raw-trace= <bytes>@<addr>
+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<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
+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 <runtime-root>/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)