1 files changed, 157 insertions, 0 deletions
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)