diff options
Diffstat (limited to 'man/libmcpu.7')
| -rw-r--r-- | man/libmcpu.7 | 160 |
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) |