Version 0.4.00.4.0

1 files changed, 160 insertions, 0 deletions

diff --git a/man/libmcpu.7 b/man/libmcpu.7
new file mode 100644
index 0000000..bfaa765
--- /dev/null
+++ b/man/libmcpu.7
@@ -0,0 +1,160 @@
+.TH LIBMCPU 7 "October 2026" "LibMCPU" "MCPU Architecture and Toolchain"
+
+.SH NAME
+libmcpu \- MCPU virtual CPU architecture, MELF ABI and binary toolchain
+.SH DESCRIPTION
+LibMCPU is a software CPU and system-programming toolchain built on LibMPU and
+LibMPUIO.  It defines the MCPU instruction set, register file, segmented PTR64
+addressing, CALL and lifecycle ABIs, the MELF object/executable format, startup
+dynamic linking and host-side execution supervisor.
+.PP
+The current toolchain reads MELF ET_REL, ET_EXEC and ET_DYN objects.  Static
+executables use ABI v1.  Historical explicit-preload dynamic files use ABI v2.
+The current normal dynamic contract is frozen MELF ABI v3 with .dynamic,
+DT_SONAME and DT_NEEDED.  Incompatible execution-format changes require a new
+MELF ABI number; auxiliary non-ALLOC development metadata does not.
+.SH ARCHITECTURAL ADDRESS SPACES
+PTR64 uses bits 63..60 as a segment selector and bits 59..0 as byte offset.
+Current selectors are DATA=0, STACK=1, PROGRAM=2, CONTROL=3, INPUT=4, OUTPUT=5,
+TRACE=6 and HEAP=7.  PROGRAM, CONTROL and INPUT are guest read-only; DATA,
+STACK, OUTPUT, TRACE and HEAP are writable according to the runtime contract.
+.SH PROGRAM STATUS WORD
+PSW bits 0..7 form the writable CPU flag byte and bits 8..15 form the writable
+MPU flag byte.  SETF/CLRF change exactly one named flag in bits 0..15;
+CLRCPUF clears bits 0..7 and CLRMPUF clears bits 8..15.  HF, TF, IF and MODE
+are execution/control state and are not writable through these arithmetic/status
+flag instructions.  JSET/JCLR retain their wider read-only selector contract.
+.SH LOW-LEVEL LIFECYCLE
+Every ET_EXEC has mandatory _start and _life lifecycle symbols; e_entry always
+addresses _start.  An executable may place _start in optional .init and may
+provide optional .fini/_fini.  END returns control to the supervisor at managed
+INIT, LIFE and FINI boundaries.  A low-level executable owns these lifecycle
+symbols itself and receives no automatic HLL CRT.
+.SH HLL RUNTIME ABI V1
+Final executable linking also recognizes compiler-normalized HLL complete-program
+objects.  A PROGRAM defining ET_REL contains strong GLOBAL/FUNC main and fini in
+one object.  A MODEL defining ET_REL contains strong GLOBAL/FUNC init, life and
+fini in one object.  PROGRAM main is incompatible with MODEL init/life, and HLL
+complete-program roots cannot be mixed with low-level _start/_life ownership.
+This is an object-level contract: if a source language makes fini optional, its
+compiler must synthesize an empty strong fini while normalizing the ET_REL.
+.PP
+The binary signatures are:
+.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
+The loader constructs one persistent 32-byte McpuStartup v1 object before
+_start.  It contains version, size, uint64 argc, PTR64 argv and a reserved zero
+field.  CRT validates this object, requires argc to fit target signed int64,
+reuses the loader-owned persistent argv array, and invokes main/init through the
+ordinary CALL ABI.  HLL functions return with RET; END and EXIT remain CRT/MELF
+lifecycle operations.
+.PP
+MODEL life returns INT32_MIN (-2147483648) to continue through exactly one LIFE
+END boundary, zero for normal completion, or a positive status for an error
+exit.  Other negative values are reserved by HLL Runtime ABI v1.
+.SH HLL CRT
+For final static or dynamic ET_EXEC links, mcpu-ld classifies the explicit input
+ET_REL objects before library extraction.  PROGRAM selects crt0.o; MODEL selects
+crt1.o.  Both forms also insert crti.o before user objects and crtn.o after user
+objects.  The objects are loaded only from:
+.nf
+<MCPU-root>/lib/mcpu/
+.fi
+A missing or invalid required CRT object is a fatal link error.  There is no
+fallback to another root and no fallback from HLL to low-level linking.
+.PP
+Startup calls __mcpu_libc_init and __mcpu_init_array before entering the HLL
+program/model.  Graceful HLL finalization calls user fini, __mcpu_fini_array and
+__mcpu_libc_fini before the final FINI END.  A failure before runtime startup
+completes remains PRE_RUNTIME and skips all HLL finalizers.  Normal DT_NEEDED
+MCPU Libc dependencies may provide the four internal runtime hooks; explicit
+preload interposition may not replace them.
+.SH TOOLCHAIN
+.TP
+.BR mcpu-as (1)
+Assembler producing MELF ET_REL.
+.TP
+.BR mcpu-ld (1)
+Static/dynamic final linker and partial ET_REL linker.
+.TP
+.BR mcpu-run (1)
+Loader, startup linker, execution supervisor and host-side test bench.
+.TP
+.BR mcpu-readelf (1)
+Structured read-only MELF inspection.
+.TP
+.BR mcpu-ar (1)
+Deterministic UNIX static-archive manager.
+.TP
+.BR mcpu-nm (1)
+Symbol inspection for MELF files and archives.
+.TP
+.BR mcpu-objdump (1)
+Section, relocation and instruction disassembly/inspection.
+.TP
+.BR mcpu-strip (1)
+Conservative removal of non-runtime symbol metadata.
+.TP
+.BR mcpu-objcopy (1)
+Safe MELF-to-MELF metadata copy/edit operations.
+.SH INSTALLATION LAYOUT
+For the conventional configuration --prefix=/usr --libdir=/usr/lib64,
+private commands live below /usr/lib64/mcpu/bin and public command names are
+symbolic links in /usr/bin.  The runtime root is relocatable and is derived from
+the real command location unless an explicit --sys-root is used by tools that
+support it.
+.PP
+The library-search configuration chain used by mcpu-ld and mcpu-run is:
+.nf
+<runtime-root>/etc/mcpu-ld.conf
+/etc/mcpu/mcpu-ld.conf
+$HOME/.mcpu/etc/mcpu-ld.conf
+.fi
+.PP
+The canonical target CRT is installed under:
+.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 AND DEBUG METADATA
+MELF is the native MCPU object and executable container; the toolchain does not
+need flat firmware images for normal execution.  Development/debug information
+can be represented as optional non-ALLOC metadata outside PT_LOAD and outside
+the runtime dynamic-link contract.  Such metadata can evolve under its own
+format version and can be removed without changing frozen MELF ABI v3 or guest
+execution semantics.
+.SH DOCUMENTATION
+The LibMCPU release contains the maintained Russian PDF references:
+.nf
+doc/libmcpu-bytecode-architecture-ru.pdf
+doc/libmcpu-melf-abi-ru.pdf
+.fi
+Editable XeLaTeX sources are under doc/src/.
+.SH FILES
+.TP
+.I /usr/include/libmcpu.h
+Public CPU architecture and operation declarations.
+.TP
+.I /usr/include/mcpu-elf.h
+Public MELF constants and record declarations.
+.TP
+.I /usr/lib64/pkgconfig/libmcpu.pc
+Pkg-config metadata for a conventional /usr,/usr/lib64 installation.
+.SH SEE ALSO
+.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)