Version 0.4.00.4.0

11 files changed, 1018 insertions, 0 deletions

diff --git a/man/ru/Makefile.am b/man/ru/Makefile.am
new file mode 100644
index 0000000..21e1639
--- /dev/null
+++ b/man/ru/Makefile.am
@@ -0,0 +1,18 @@
+
+LANG = ru
+
+mandir = @mandir@/$(LANG)
+
+MAN1 = mcpu-as.1       \
+       mcpu-ld.1       \
+       mcpu-run.1      \
+       mcpu-readelf.1  \
+       mcpu-ar.1       \
+       mcpu-nm.1       \
+       mcpu-objdump.1  \
+       mcpu-strip.1    \
+       mcpu-objcopy.1
+
+MAN7 = libmcpu.7
+
+dist_man_MANS = $(MAN1) $(MAN7)
diff --git a/man/ru/libmcpu.7 b/man/ru/libmcpu.7
new file mode 100644
index 0000000..8003296
--- /dev/null
+++ b/man/ru/libmcpu.7
@@ -0,0 +1,157 @@
+.TH LIBMCPU 7 "Октябрь 2026" "LibMCPU" "Архитектура и инструментарий MCPU"
+
+.SH ИМЯ
+libmcpu \- виртуальный CPU MCPU, MELF ABI и бинарный toolchain
+.SH ОПИСАНИЕ
+LibMCPU — программный CPU и system-programming toolchain на базе LibMPU и
+LibMPUIO. Он определяет ISA MCPU, register file, segmented PTR64, CALL и
+lifecycle ABI, объектный/исполняемый формат MELF, startup dynamic linking и
+host-side execution supervisor.
+.PP
+Toolchain читает MELF ET_REL, ET_EXEC и ET_DYN. Статические executable
+используют ABI v1; historical explicit-preload dynamic files — ABI v2; текущий
+normal dynamic contract — frozen MELF ABI v3 с .dynamic, DT_SONAME и DT_NEEDED.
+Несовместимое изменение execution format требует нового MELF ABI number;
+дополнительные non-ALLOC development metadata его не требуют.
+.SH АРХИТЕКТУРНЫЕ ПРОСТРАНСТВА
+PTR64 использует bits 63..60 как segment selector и 59..0 как byte offset.
+Селекторы: DATA=0, STACK=1, PROGRAM=2, CONTROL=3, INPUT=4, OUTPUT=5, TRACE=6,
+HEAP=7. PROGRAM, CONTROL и INPUT guest read-only; DATA, STACK, OUTPUT, TRACE и
+HEAP writable в рамках runtime contract.
+.SH СЛОВО СОСТОЯНИЯ PSW
+PSW bits 0..7 образуют writable CPU flag byte, а bits 8..15 — writable MPU
+flag byte. SETF/CLRF изменяют ровно один именованный flag в диапазоне 0..15;
+CLRCPUF очищает bits 0..7, CLRMPUF — bits 8..15. HF, TF, IF и MODE относятся
+к execution/control state и этими arithmetic/status instructions не записываются.
+JSET/JCLR сохраняют более широкий read-only selector contract.
+.SH НИЗКОУРОВНЕВЫЙ LIFECYCLE
+Каждый ET_EXEC имеет обязательные _start и _life; e_entry всегда адресует
+_start. Executable может размещать _start в optional .init и иметь optional
+.fini/_fini. END возвращает управление supervisor на управляемых границах INIT,
+LIFE и FINI. Низкоуровневый executable сам владеет lifecycle symbols и не
+получает automatic HLL CRT.
+.SH HLL RUNTIME ABI V1
+Final executable link также распознаёт compiler-normalized HLL complete-program
+objects. PROGRAM defining ET_REL содержит strong GLOBAL/FUNC main и fini в одном
+object. MODEL defining ET_REL содержит strong GLOBAL/FUNC init, life и fini в
+одном object. PROGRAM main несовместим с MODEL init/life; HLL complete-program
+roots нельзя смешивать с низкоуровневым владением _start/_life.
+Это object-level contract: если source language делает fini optional, compiler
+обязан синтезировать empty strong fini при нормализации ET_REL.
+.PP
+Binary signatures:
+.nf
+PROGRAM: int32 main(int64 argc, PTR64 argv)
+         void  fini(void)
+MODEL:   int32 init(int64 argc, PTR64 argv)
+         int32 life(void)
+         void  fini(void)
+.fi
+.PP
+Перед _start loader один раз создаёт постоянный 32-byte McpuStartup v1:
+version, size, uint64 argc, PTR64 argv и reserved zero field. CRT проверяет эту
+структуру, требует представимость argc в target signed int64, повторно использует
+loader-owned persistent argv и вызывает main/init через обычный CALL ABI. HLL
+functions завершаются RET; END и EXIT остаются операциями CRT/MELF lifecycle.
+.PP
+MODEL life возвращает INT32_MIN (-2147483648) для продолжения через ровно одну
+LIFE END boundary, zero для нормального завершения модели и positive status для
+error exit. Остальные отрицательные значения зарезервированы HLL Runtime ABI v1.
+.SH HLL CRT
+Для final static/dynamic ET_EXEC link mcpu-ld классифицирует явные входные
+ET_REL objects до извлечения библиотек. PROGRAM выбирает crt0.o, MODEL — crt1.o;
+в обоих случаях crti.o вставляется перед user objects, а crtn.o после них.
+Объекты загружаются только из:
+.nf
+<MCPU-root>/lib/mcpu/
+.fi
+Отсутствующий или повреждённый обязательный CRT object является fatal link
+error. Перехода к другому root и fallback из HLL в low-level linking нет.
+.PP
+Startup вызывает __mcpu_libc_init и __mcpu_init_array до входа в HLL
+program/model. Graceful HLL finalization вызывает user fini,
+__mcpu_fini_array и __mcpu_libc_fini перед финальным FINI END. Ошибка до
+завершения runtime startup остаётся PRE_RUNTIME и пропускает HLL finalizers.
+Обычная DT_NEEDED MCPU Libc dependency может предоставлять четыре internal
+runtime hooks; explicit preload не может их подменять.
+.SH TOOLCHAIN
+.TP
+.BR mcpu-as (1)
+Assembler MELF ET_REL.
+.TP
+.BR mcpu-ld (1)
+Final/static/dynamic и partial ET_REL linker.
+.TP
+.BR mcpu-run (1)
+Loader, startup linker, execution supervisor и host-side test bench.
+.TP
+.BR mcpu-readelf (1)
+Structured read-only MELF inspection.
+.TP
+.BR mcpu-ar (1)
+Deterministic UNIX static archives.
+.TP
+.BR mcpu-nm (1)
+Symbol inspection.
+.TP
+.BR mcpu-objdump (1)
+Sections, relocations и disassembly.
+.TP
+.BR mcpu-strip (1)
+Conservative non-runtime symbol stripping.
+.TP
+.BR mcpu-objcopy (1)
+Safe MELF-to-MELF metadata editing.
+.SH INSTALLATION LAYOUT
+При --prefix=/usr --libdir=/usr/lib64 private commands находятся в
+/usr/lib64/mcpu/bin, а public names являются symlinks в /usr/bin. Runtime root
+перемещаем и обычно выводится из реального пути executable; инструменты с
+--sys-root могут выбрать другой root явно.
+.PP
+Configuration chain mcpu-ld/mcpu-run:
+.nf
+<runtime-root>/etc/mcpu-ld.conf
+/etc/mcpu/mcpu-ld.conf
+$HOME/.mcpu/etc/mcpu-ld.conf
+.fi
+.PP
+Canonical target CRT устанавливается в:
+.nf
+<runtime-root>/lib/mcpu/crt0.o
+<runtime-root>/lib/mcpu/crt1.o
+<runtime-root>/lib/mcpu/crti.o
+<runtime-root>/lib/mcpu/crtn.o
+.fi
+.SH MELF И DEBUG METADATA
+MELF — native MCPU object/executable container; для обычного исполнения не
+нужны flat firmware images. Development/debug information может жить как
+необязательная non-ALLOC metadata вне PT_LOAD и runtime dynamic-link contract.
+Такая metadata может иметь собственную версию формата и удаляться без изменения
+frozen MELF ABI v3 и guest execution semantics.
+.SH ДОКУМЕНТАЦИЯ
+В release входят русские PDF references:
+.nf
+doc/libmcpu-bytecode-architecture-ru.pdf
+doc/libmcpu-melf-abi-ru.pdf
+.fi
+Editable XeLaTeX sources находятся в doc/src/.
+.SH ФАЙЛЫ
+.TP
+.I /usr/include/libmcpu.h
+Public CPU declarations.
+.TP
+.I /usr/include/mcpu-elf.h
+Public MELF constants/records.
+.TP
+.I /usr/lib64/pkgconfig/libmcpu.pc
+Pkg-config metadata при обычной /usr,/usr/lib64 установке.
+.SH СМ. ТАКЖЕ
+.BR mcpu-as (1),
+.BR mcpu-ld (1),
+.BR mcpu-run (1),
+.BR mcpu-readelf (1),
+.BR mcpu-ar (1),
+.BR mcpu-nm (1),
+.BR mcpu-objdump (1),
+.BR mcpu-strip (1),
+.BR mcpu-objcopy (1)
diff --git a/man/ru/mcpu-ar.1 b/man/ru/mcpu-ar.1
new file mode 100644
index 0000000..d19db3f
--- /dev/null
+++ b/man/ru/mcpu-ar.1
@@ -0,0 +1,70 @@
+.TH MCPU-AR 1 "Октябрь 2026" "LibMCPU" "Команды пользователя"
+
+.SH ИМЯ
+mcpu-ar \- manager deterministic static archives MCPU
+.SH СИНТАКСИС
+.B mcpu-ar
+.RI [ опции ] " операция архив " [ member ...]
+.SH ОПИСАНИЕ
+.B mcpu-ar
+создаёт deterministic UNIX ar archives с MELF ET_REL members. Порядок members
+сохраняется. Операция/модификатор s строит System-V/GNU-style symbol index,
+который использует
+.BR mcpu-ld (1)
+при selective extraction.
+.SH ОПЕРАЦИИ
+.TP
+.B r
+Заменить existing members на месте или добавить новые.
+.TP
+.B q
+Всегда добавить members без replacement.
+.TP
+.B d
+Удалить named members.
+.TP
+.B t
+Список members.
+.TP
+.B p
+Вывести содержимое member в stdout.
+.TP
+.B x
+Извлечь members в текущий каталог.
+.TP
+.B s
+Перестроить symbol index.
+.SH МОДИФИКАТОРЫ
+.TP
+.B c
+Compatibility modifier; создание архива тихое.
+.TP
+.B s
+Записать/rebuild symbol index.
+.TP
+.B v
+Verbose operation.
+.PP
+Операция и modifiers объединяются: rcs, tv, xv.
+.SH ОПЦИИ
+.TP
+.B --help
+Справка.
+.TP
+.B --version
+Вывести имя программы, идентификатор инструментария MCPU и версию, затем завершить работу.
+.TP
+.B --dump-version
+Вывести только номер версии пакета MCPU и завершить работу.
+.SH ПРИМЕРЫ
+.nf
+mcpu-ar rcs libsimple.a add-one.o add-two.o value.o
+mcpu-ar t libsimple.a
+mcpu-ar tv libsimple.a
+mcpu-ar x libsimple.a add-one.o
+.fi
+.SH СМ. ТАКЖЕ
+.BR mcpu-ld (1),
+.BR mcpu-nm (1),
+.BR mcpu-objdump (1),
+.BR libmcpu (7)
diff --git a/man/ru/mcpu-as.1 b/man/ru/mcpu-as.1
new file mode 100644
index 0000000..96d79ed
--- /dev/null
+++ b/man/ru/mcpu-as.1
@@ -0,0 +1,79 @@
+.TH MCPU-AS 1 "Октябрь 2026" "LibMCPU" "Команды пользователя"
+
+.SH ИМЯ
+mcpu-as \- ассемблер исходного текста MCPU в перемещаемый объект MELF
+.SH СИНТАКСИС
+.B mcpu-as
+.RI [ опции ] " -o output.o input.s"
+.SH ОПИСАНИЕ
+.B mcpu-as
+читает один исходный файл ассемблера MCPU в UTF-8 и создаёт один перемещаемый
+объект MELF
+.BR ET_REL .
+Отдельного режима compile-only нет: ET_REL является нормальным и единственным
+объектным выходом ассемблера. Исходный файл и
+.B -o
+могут находиться в любом порядке.
+.PP
+Assembler записывает symbols, sections и relocations, явно заданные исходным
+текстом; он не выбирает PROGRAM или MODEL и не синтезирует HLL CRT objects.
+Final lifecycle ownership, automatic HLL CRT selection, STACK и HEAP program
+headers определяются позднее командой
+.BR mcpu-ld (1).
+.SH ОПЦИИ
+.TP
+.BI -o " файл"
+Записать объект в указанный файл. Опция обязательна.
+.TP
+.BR -v ", " --verbose
+После успешной сборки вывести краткую сводку о созданном MELF ET_REL object.
+По умолчанию успешный запуск ничего не выводит.
+.TP
+.BR -h ", " --help
+Вывести справку и завершиться.
+.TP
+.B --version
+Вывести имя программы, идентификатор инструментария MCPU и версию, затем завершить работу.
+.TP
+.B --dump-version
+Вывести только номер версии пакета MCPU и завершить работу.
+.SH УПРАВЛЕНИЕ ФЛАГАМИ PSW
+Ассемблер принимает явные инструкции управления arithmetic/status flags:
+.nf
+SETF flag
+CLRF flag
+CLRCPUF
+CLRMPUF
+.fi
+.PP
+.B SETF
+и
+.B CLRF
+принимают именованные флаги AF, CF, OF, SF, PF, ZF, RF, VF, DOMF, SNGF,
+OVFF, UDFF, TLSF, PLSF, INDF и INXF, то есть PSW bits 0..15. HF, TF и IF
+остаются допустимыми selectors для чтения через условные переходы, но этими
+инструкциями не записываются; MODE является многобитовым полем и selector не
+имеет.
+.B CLRCPUF
+очищает PSW[7:0], а
+.B CLRMPUF
+очищает PSW[15:8]. Обе инструкции сохраняют control/execution state выше bit 15.
+.SH УПРАВЛЕНИЕ ИСХОДНОЙ ПОЗИЦИЕЙ
+Ассемблер принимает директиву
+.B #line
+с десятичным номером строки и необязательным именем файла в кавычках. Она
+предназначена для вывода препроцессора, меняет последующие позиции диагностик и
+не записывается в MELF.
+.SH СТАТУС ЗАВЕРШЕНИЯ
+Ноль при успехе; ненулевое значение при синтаксической, семантической, I/O или
+object-generation ошибке.
+.SH ПРИМЕРЫ
+.nf
+mcpu-as -o main.o main.s
+mcpu-as helper.s -o helper.o
+.fi
+.SH СМ. ТАКЖЕ
+.BR mcpu-ld (1),
+.BR mcpu-readelf (1),
+.BR mcpu-objdump (1),
+.BR libmcpu (7)
diff --git a/man/ru/mcpu-ld.1 b/man/ru/mcpu-ld.1
new file mode 100644
index 0000000..b57cb93
--- /dev/null
+++ b/man/ru/mcpu-ld.1
@@ -0,0 +1,170 @@
+.TH MCPU-LD 1 "Октябрь 2026" "LibMCPU" "Команды пользователя"
+
+.SH ИМЯ
+mcpu-ld \- компоновщик объектов, архивов и shared libraries MCPU
+.SH СИНТАКСИС
+.B mcpu-ld
+.RI [ опции-компоновки ] " -o output input ..."
+.SH ОПИСАНИЕ
+.B mcpu-ld
+компонует MELF ET_REL objects и статические библиотеки MCPU. Он создаёт partial
+ET_REL, полностью статический ABI-v1 ET_EXEC, frozen ABI-v3 startup-dynamic
+ET_EXEC или ABI-v3 ET_DYN shared object.
+.PP
+Без
+.BR -r ,
+.B --shared
+и
+.B --dynamic
+по умолчанию создаётся статический ABI-v1 ET_EXEC.
+.SH РЕЖИМЫ ВЫХОДА
+.TP
+.B -r
+Создать один partial-link MELF ET_REL. Неразрешённые strong symbols и RELA
+могут остаться для последующей final link. STACK, HEAP, SONAME и shared objects
+к этому режиму не относятся.
+.TP
+.B --shared
+Создать frozen ABI-v3 MELF ET_DYN. Обязателен логический
+.BR --soname .
+Shared object может иметь только allocated .text/.data/.bss и не владеет
+lifecycle, model spaces, STACK или HEAP.
+.TP
+.B --dynamic
+Создать frozen ABI-v3 startup-dynamic MELF ET_EXEC. Normal dependencies
+записываются как DT_NEEDED SONAME.
+.SH AUTOMATIC HLL CRT
+Для final static/dynamic ET_EXEC output mcpu-ld сначала анализирует явно
+перечисленные входные ET_REL objects и только затем обрабатывает -l libraries.
+Распознаются две compiler-normalized complete-program формы:
+.nf
+PROGRAM: strong GLOBAL/FUNC main + fini в одном ET_REL
+MODEL:   strong GLOBAL/FUNC init + life + fini в одном ET_REL
+.fi
+.PP
+PROGRAM и MODEL roots взаимоисключающие. Incomplete или split MODEL definitions
+отклоняются; PROGRAM main/fini также должны принадлежать одному defining ET_REL.
+Смешивание HLL roots с низкоуровневым владением _start/_life является ошибкой.
+Library members и shared-library definitions не участвуют в классификации
+complete program.
+.PP
+После классификации mcpu-ld автоматически вставляет:
+.nf
+PROGRAM: crt0.o crti.o <explicit input objects> crtn.o
+MODEL:   crt1.o crti.o <explicit input objects> crtn.o
+.fi
+CRT objects загружаются из <MCPU-root>/lib/mcpu, где <MCPU-root> — активный
+installation/system root. Отсутствующий или нечитаемый обязательный CRT object
+является fatal error. Поиска fallback CRT в другом root и перехода HLL link в
+low-level linking нет.
+.PP
+Low-level ET_EXEC inputs, самостоятельно владеющие _start/_life, компонуются без
+HLL CRT insertion. Режимы -r и --shared не выполняют HLL complete-program
+classification или CRT insertion.
+.SH SYSTEM ROOT И CONFIGURATION
+.TP
+.B --no-config
+Не читать mcpu-ld.conf; executable-derived runtime root и его default lib
+остаются активными.
+.TP
+.BI --sys-root= ПУТЬ
+Использовать ПУТЬ как MCPU system root, не читать configuration files и взять
+ПУТЬ/lib как системный каталог библиотек. Относительный путь разрешается от
+рабочего каталога запуска.
+.TP
+.BI --sys-root " ПУТЬ"
+Эквивалентная двухаргументная форма.
+.TP
+.B --dump-config
+Вывести effective MCPU configuration и завершиться.
+.TP
+.B --print-search-dirs
+Вывести effective library search directories в порядке поиска и завершиться.
+.SH БИБЛИОТЕКИ
+.TP
+.BI -L " каталог"
+.TQ
+.BI -L каталог
+Добавить явный каталог поиска. -L каталоги идут раньше configured system path.
+.TP
+.BI -l " имя"
+.TQ
+.BI -l имя
+Искать libИМЯ. ABI-v1 и -r рассматривают только libИМЯ.a; ABI-v3 dynamic/shared
+в каждом каталоге сначала рассматривает libИМЯ.so, затем libИМЯ.a.
+.TP
+.B --static
+Принудить все -l искать только libИМЯ.a, не меняя выбранный output mode.
+Архивные members встраиваются статически и не создают DT_NEEDED.
+.SH SHARED-LIBRARY IDENTITY
+.TP
+.BI --soname= ИМЯ
+.TQ
+.BI --soname " ИМЯ"
+Установить обязательный SONAME ABI-v3 ET_DYN. Логическое ИМЯ не должно содержать '/'.
+.SH ПАРАМЕТРЫ EXECUTABLE
+.TP
+.BI -o " файл"
+Записать результат в файл.
+.TP
+.BI --stack-size= размер
+Фиксированный размер STACK; положительный и кратный 16. Default 1048576.
+.TP
+.BI --heap-size= размер
+Начальный HEAP. Default 1048576.
+.TP
+.BI --heap-limit= размер
+Неизменяемый maximum HEAP. Default 1048576.
+.TP
+.B --no-heap
+Не создавать PT_MCPU_HEAP.
+.TP
+.BR -v ", " --verbose
+После успешной компоновки вывести краткую сводку о созданном MELF object.
+По умолчанию успешный запуск ничего не выводит.
+.TP
+.BR -h ", " --help
+Вывести справку.
+.TP
+.B --version
+Вывести имя программы, идентификатор инструментария MCPU и версию, затем завершить работу.
+.TP
+.B --dump-version
+Вывести только номер версии пакета MCPU и завершить работу.
+.PP
+Размер по умолчанию задаётся в байтах. Поддерживаются K/KiB, M/MiB, G/GiB;
+K, M, G используют двоичные множители.
+.SH АРХИВЫ И SYMBOL RESOLUTION
+Статические библиотеки MCPU — обычные deterministic UNIX ar containers с MELF
+ET_REL members. Member извлекается, когда он удовлетворяет текущему
+неразрешённому strong GLOBAL symbol. Один unresolved WEAK сам по себе member не
+вытягивает.
+.SH ФАЙЛЫ
+.TP
+.I <runtime-root>/lib/mcpu/crt0.o, crt1.o, crti.o, crtn.o
+Обязательные automatic HLL CRT objects для final PROGRAM/MODEL executable link.
+.TP
+.I <runtime-root>/etc/mcpu-ld.conf
+Configuration из переносимого дерева MCPU.
+.TP
+.I /etc/mcpu/mcpu-ld.conf
+Необязательный machine-wide override.
+.TP
+.I $HOME/.mcpu/etc/mcpu-ld.conf
+Необязательный user override.
+.SH СТАТУС ЗАВЕРШЕНИЯ
+Ноль при успехе; ненулевое значение при ошибке опций, validation, symbol
+resolution, relocation или записи результата.
+.SH ПРИМЕРЫ
+.nf
+mcpu-ld --stack-size=64K --no-heap -o program main.o helper.o
+mcpu-ld -r -o combined.o a.o b.o
+mcpu-ld --shared --soname=libfoo.so.1 -o libfoo.so.1.0.0 foo.o
+mcpu-ld --dynamic -L ./lib -lfoo -o program main.o
+.fi
+.SH СМ. ТАКЖЕ
+.BR mcpu-as (1),
+.BR mcpu-ar (1),
+.BR mcpu-run (1),
+.BR mcpu-readelf (1),
+.BR libmcpu (7)
diff --git a/man/ru/mcpu-nm.1 b/man/ru/mcpu-nm.1
new file mode 100644
index 0000000..b58db53
--- /dev/null
+++ b/man/ru/mcpu-nm.1
@@ -0,0 +1,59 @@
+.TH MCPU-NM 1 "Октябрь 2026" "LibMCPU" "Команды пользователя"
+
+.SH ИМЯ
+mcpu-nm \- вывод символов MELF-файлов и архивов MCPU
+.SH СИНТАКСИС
+.B mcpu-nm
+.RI [ опции ] " MELF-файл(ы)"
+.SH ОПИСАНИЕ
+.B mcpu-nm
+показывает symbols из ET_REL, ET_EXEC, ET_DYN и deterministic MCPU archives.
+По умолчанию читается .symtab и сортировка идёт по имени; для runtime symbols
+используется
+.BR -D .
+.SH ОПЦИИ
+.TP
+.BR -a ", " --debug-syms
+Все named symbols, включая FILE/SECTION.
+.TP
+.BR -g ", " --extern-only
+Только external GLOBAL/WEAK.
+.TP
+.BR -u ", " --undefined-only
+Только undefined symbols.
+.TP
+.BR -n ", " --numeric-sort
+Сортировка по value.
+.TP
+.BR -r ", " --reverse-sort
+Обратный выбранный порядок.
+.TP
+.BR -p ", " --no-sort
+Порядок symbol table.
+.TP
+.BR -D ", " --dynamic
+Использовать .dynsym вместо .symtab.
+.TP
+.BR -A ", " --print-file-name
+Префиксовать каждую строку именем input; для archive указывается archive/member.
+.TP
+.B --help
+Справка.
+.TP
+.B --version
+Вывести имя программы, идентификатор инструментария MCPU и версию, затем завершить работу.
+.TP
+.B --dump-version
+Вывести только номер версии пакета MCPU и завершить работу.
+.SH ПРИМЕРЫ
+.nf
+mcpu-nm file.o
+mcpu-nm -n file.o
+mcpu-nm -D libfoo.so.1
+mcpu-nm -A -D -g libfoo.so.1
+mcpu-nm -A libsimple.a
+.fi
+.SH СМ. ТАКЖЕ
+.BR mcpu-readelf (1),
+.BR mcpu-objdump (1),
+.BR libmcpu (7)
diff --git a/man/ru/mcpu-objcopy.1 b/man/ru/mcpu-objcopy.1
new file mode 100644
index 0000000..204aa9e
--- /dev/null
+++ b/man/ru/mcpu-objcopy.1
@@ -0,0 +1,71 @@
+.TH MCPU-OBJCOPY 1 "Октябрь 2026" "LibMCPU" "Команды пользователя"
+
+.SH ИМЯ
+mcpu-objcopy \- безопасное копирование и редактирование metadata MELF
+.SH СИНТАКСИС
+.B mcpu-objcopy
+.RI [ опции ] " INPUT OUTPUT"
+.SH ОПИСАНИЕ
+.B mcpu-objcopy
+— MELF-to-MELF structural copier/editor. Это намеренно не ROM-image converter:
+нет flat binary, Intel HEX, S-record, VMA/LMA, start-address или section-flags
+conversion modes.
+.PP
+Editor защищает frozen MELF ABI v3: runtime-visible allocated sections,
+dynamic-link metadata, runtime relocations и MCPU target/lifecycle data нельзя
+удалять, переименовывать или изменять safe metadata interface.
+.SH ОПЦИИ
+.TP
+.BI -j " ИМЯ"
+.TQ
+.BI --only-section= ИМЯ
+Копировать только указанные sections; repeatable. Операция отклоняется, если
+фильтрация выбрасывает runtime, dynamic или ET_REL link-critical data.
+.TP
+.BI -R " ИМЯ"
+.TQ
+.BI --remove-section= ИМЯ
+Удалить safe non-runtime section.
+.TP
+.BI --dump-section= ИМЯ=ФАЙЛ
+Записать contents section в ФАЙЛ. Для archive input отклоняется как
+неоднозначная операция.
+.TP
+.BI --add-section= ИМЯ=ФАЙЛ
+Добавить non-ALLOC SHT_PROGBITS metadata из ФАЙЛ. Reserved runtime names
+запрещены.
+.TP
+.BI --update-section= ИМЯ=ФАЙЛ
+Заменить contents safe non-ALLOC SHT_PROGBITS section.
+.TP
+.BI --rename-section= СТАРОЕ=НОВОЕ
+Переименовать safe non-ALLOC section; reserved runtime names защищены.
+.TP
+.B --help
+Справка.
+.TP
+.B --version
+Вывести имя программы, идентификатор инструментария MCPU и версию, затем завершить работу.
+.TP
+.B --dump-version
+Вывести только номер версии пакета MCPU и завершить работу.
+.SH STRUCTURAL INVARIANTS
+Metadata-only edits перестраивают .shstrtab и remap section references,
+включая st_shndx сохраняемых symbols, но не изменяют allocated image и program
+headers. Non-ALLOC metadata tail может быть repacked.
+.SH АРХИВЫ
+Deterministic MCPU archives преобразуются member-by-member с сохранением
+archive symbol-index semantics.
+.SH ПРИМЕРЫ
+.nf
+mcpu-objcopy input.o output.o
+mcpu-objcopy --add-section=.note.build=build.txt input.o output.o
+mcpu-objcopy --update-section=.note.build=new.txt input.o output.o
+mcpu-objcopy --rename-section=.note.build=.note.release input.o output.o
+mcpu-objcopy -R .note.release input.o output.o
+.fi
+.SH СМ. ТАКЖЕ
+.BR mcpu-strip (1),
+.BR mcpu-objdump (1),
+.BR mcpu-readelf (1),
+.BR libmcpu (7)
diff --git a/man/ru/mcpu-objdump.1 b/man/ru/mcpu-objdump.1
new file mode 100644
index 0000000..ec2dcd4
--- /dev/null
+++ b/man/ru/mcpu-objdump.1
@@ -0,0 +1,66 @@
+.TH MCPU-OBJDUMP 1 "Октябрь 2026" "LibMCPU" "Команды пользователя"
+
+.SH ИМЯ
+mcpu-objdump \- секции, relocations и дизассемблирование инструкций MCPU
+.SH СИНТАКСИС
+.B mcpu-objdump
+.RI [ опции ] " MELF-файл(ы)"
+.SH ОПИСАНИЕ
+.B mcpu-objdump
+просматривает MELF objects, executables, shared objects и deterministic
+archives. Дизассемблер использует тот же LibMCPU instruction decoder, что и
+runtime, а symbol/relocation information применяется для аннотаций без
+подмены raw operand bytes.
+.SH ОПЦИИ
+.TP
+.BR -d ", " --disassemble
+Дизассемблировать executable PROGBITS sections.
+.TP
+.BR -D ", " --disassemble-all
+Пытаться дизассемблировать все выбранные nonempty PROGBITS.
+.TP
+.BR -r ", " --reloc
+Показать relocations; при disassembly relocation привязывается к инструкции,
+содержащей поле relocation.
+.TP
+.BR -s ", " --full-contents
+Raw contents sections.
+.TP
+.BR -t ", " --syms
+.symtab symbols.
+.TP
+.BR -T ", " --dynamic-syms
+.dynsym symbols.
+.TP
+.BR -h ", " --section-headers
+Section headers.
+.TP
+.BI -j " ИМЯ"
+.TQ
+.BI --section= ИМЯ
+Ограничить section-oriented output; repeatable.
+.TP
+.B --help
+Справка.
+.TP
+.B --version
+Вывести имя программы, идентификатор инструментария MCPU и версию, затем завершить работу.
+.TP
+.B --dump-version
+Вывести только номер версии пакета MCPU и завершить работу.
+.PP
+Нужна хотя бы одна display option. Нераспознаваемые bytes печатаются как
+.byte, после чего просмотр продолжается.
+.SH ПРИМЕРЫ
+.nf
+mcpu-objdump -h file.o
+mcpu-objdump -t -r -d file.o
+mcpu-objdump -T -d -r libfoo.so.1
+mcpu-objdump -s -j .data file.o
+mcpu-objdump -d libsimple.a
+.fi
+.SH СМ. ТАКЖЕ
+.BR mcpu-readelf (1),
+.BR mcpu-nm (1),
+.BR mcpu-objcopy (1),
+.BR libmcpu (7)
diff --git a/man/ru/mcpu-readelf.1 b/man/ru/mcpu-readelf.1
new file mode 100644
index 0000000..2c6d1ae
--- /dev/null
+++ b/man/ru/mcpu-readelf.1
@@ -0,0 +1,76 @@
+.TH MCPU-READELF 1 "Октябрь 2026" "LibMCPU" "Команды пользователя"
+
+.SH ИМЯ
+mcpu-readelf \- структурный просмотр MELF-файлов MCPU
+.SH СИНТАКСИС
+.B mcpu-readelf
+.RI "опции MELF-файл(ы)"
+.SH ОПИСАНИЕ
+.B mcpu-readelf
+— read-only inspector для MELF ABI v1/v2/v3. Показывает headers, sections,
+symbols, RELA, dynamic dependency metadata и MCPU target/lifecycle records, не
+изменяя входные файлы.
+.SH ОПЦИИ
+.TP
+.BR -a ", " --all
+Эквивалент -h -l -S -s -r -d -A.
+.TP
+.BR -e ", " --headers
+Эквивалент -h -l -S.
+.TP
+.BR -h ", " --file-header
+Показать MELF file header.
+.TP
+.BR -l ", " --program-headers
+Показать program headers.
+.TP
+.B --segments
+Alias для --program-headers.
+.TP
+.BR -S ", " --section-headers
+Показать section headers.
+.TP
+.B --sections
+Alias для --section-headers.
+.TP
+.BR -s ", " --symbols
+Показать .symtab/.dynsym.
+.TP
+.B --syms
+Alias для --symbols.
+.TP
+.BR -r ", " --relocs
+Показать RELA sections.
+.TP
+.BR -d ", " --dynamic
+Показать ABI-v3 .dynamic, включая SONAME/NEEDED.
+.TP
+.BR -A ", " --arch-specific
+Показать MCPU target/lifecycle metadata.
+.TP
+.BR -W ", " --wide
+Не усекать вывод; compatibility option.
+.TP
+.B --help
+Справка.
+.TP
+.B --version
+Вывести имя программы, идентификатор инструментария MCPU и версию, затем завершить работу.
+.TP
+.B --dump-version
+Вывести только номер версии пакета MCPU и завершить работу.
+.SH СТАТУС ЗАВЕРШЕНИЯ
+Ноль при успешном чтении всех файлов; ненулевое значение при malformed,
+unsupported или недоступном input.
+.SH ПРИМЕРЫ
+.nf
+mcpu-readelf -h -S file.o
+mcpu-readelf -s -r file.o
+mcpu-readelf -l -A program
+mcpu-readelf -d libfoo.so.1
+mcpu-readelf -a program
+.fi
+.SH СМ. ТАКЖЕ
+.BR mcpu-nm (1),
+.BR mcpu-objdump (1),
+.BR libmcpu (7)
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)
diff --git a/man/ru/mcpu-strip.1 b/man/ru/mcpu-strip.1
new file mode 100644
index 0000000..3e437ff
--- /dev/null
+++ b/man/ru/mcpu-strip.1
@@ -0,0 +1,53 @@
+.TH MCPU-STRIP 1 "Октябрь 2026" "LibMCPU" "Команды пользователя"
+
+.SH ИМЯ
+mcpu-strip \- безопасное удаление non-runtime symbol metadata из MELF
+.SH СИНТАКСИС
+.B mcpu-strip
+.RI [ опции ] " MELF-файл"
+.SH ОПИСАНИЕ
+.B mcpu-strip
+намеренно консервативен. Он удаляет ordinary non-ALLOC SHT_SYMTAB из
+ET_EXEC/ET_DYN только когда ни одна сохраняемая section от него не зависит, и
+удаляет связанную ordinary string table только когда она становится
+unreferenced.
+.PP
+ET_REL symbol tables сохраняются как часть последующей link semantics.
+.dynsym/.dynstr/.dynamic, RELA, MCPU target/lifecycle metadata, allocated/model
+sections и program headers всегда сохраняются. Современные final-image writers
+LibMCPU уже компактны, поэтому нормальный ET_EXEC/ET_DYN часто остаётся
+byte-for-byte неизменным.
+.SH ОПЦИИ
+.TP
+.BI -o " файл"
+.TQ
+.BI --output= ФАЙЛ
+Записать отдельный результат вместо in-place replacement.
+.TP
+.B --help
+Справка.
+.TP
+.B --version
+Вывести имя программы, идентификатор инструментария MCPU и версию, затем завершить работу.
+.TP
+.B --dump-version
+Вывести только номер версии пакета MCPU и завершить работу.
+.SH IN-PLACE SAFETY
+In-place replacement выполняется через temporary file в том же каталоге и
+rename с сохранением mode исходного файла. Allocated image и program headers не
+перепаковываются safe metadata policy.
+.SH АРХИВЫ
+MCPU archives обрабатываются member-by-member; link-critical ET_REL symbols
+сохраняются.
+.SH ПРИМЕРЫ
+.nf
+mcpu-strip program
+mcpu-strip -o program.stripped program
+mcpu-strip libfoo.so.1
+mcpu-strip libsimple.a
+.fi
+.SH СМ. ТАКЖЕ
+.BR mcpu-objcopy (1),
+.BR mcpu-readelf (1),
+.BR mcpu-objdump (1),
+.BR libmcpu (7)