.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 /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 /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 /lib/mcpu/crt0.o /lib/mcpu/crt1.o /lib/mcpu/crti.o /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)