path: root/man/libmcpu.7

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