path: root/man/ru/libmcpu.7

.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)