Version 0.4.00.4.0

1 files changed, 85 insertions, 0 deletions

diff --git a/man/mcpu-as.1 b/man/mcpu-as.1
new file mode 100644
index 0000000..c4c73be
--- /dev/null
+++ b/man/mcpu-as.1
@@ -0,0 +1,85 @@
+.TH MCPU-AS 1 "October 2026" "LibMCPU" "User Commands"
+
+.SH NAME
+mcpu-as \- assemble MCPU source into a MELF relocatable object
+.SH SYNOPSIS
+.B mcpu-as
+.RI [ options ] " -o output.o input.s"
+.SH DESCRIPTION
+.B mcpu-as
+reads one UTF-8 MCPU assembler source and writes one MELF
+.B ET_REL
+relocatable object.  The assembler does not have a separate compile-only mode:
+ET_REL is its normal and only object output.  Input and the
+.B -o
+option may appear in either order.
+.PP
+The assembler records the symbols, sections and relocations explicitly described
+by the source; it does not choose PROGRAM versus MODEL and does not synthesize
+HLL CRT objects.  Final lifecycle ownership, automatic HLL CRT selection,
+STACK and HEAP program headers are resolved later by
+.BR mcpu-ld (1).
+.SH OPTIONS
+.TP
+.BI -o " file"
+Write the relocatable object to
+.IR file .
+This option is mandatory.
+.TP
+.BR -v ", " --verbose
+Print the MELF ET_REL output-object summary after successful assembly.
+The default successful invocation is quiet.
+.TP
+.BR -h ", " --help
+Display command-line help and exit.
+.SH PSW FLAG INSTRUCTIONS
+The assembler accepts explicit arithmetic/status flag control instructions:
+.nf
+SETF flag
+CLRF flag
+CLRCPUF
+CLRMPUF
+.fi
+.PP
+.B SETF
+and
+.B CLRF
+accept the named flags AF, CF, OF, SF, PF, ZF, RF, VF, DOMF, SNGF, OVFF,
+UDFF, TLSF, PLSF, INDF and INXF, corresponding to PSW bits 0 through 15.
+HF, TF and IF remain readable branch selectors but are not writable through
+these instructions; MODE is a multi-bit field and has no selector.
+.B CLRCPUF
+clears PSW[7:0], while
+.B CLRMPUF
+clears PSW[15:8].  Both preserve all control/execution state above bit 15.
+.SH SOURCE LOCATION CONTROL
+The assembler accepts the source directive
+.B #line
+with a decimal line number and an optional quoted file name.  It is intended
+for preprocessor output and changes subsequent diagnostic source locations;
+it does not become part of the MELF object.
+.SH FILES
+.TP
+.I *.s
+MCPU assembler source.
+.TP
+.I *.o
+Conventional name for MELF ET_REL output.
+.TP
+.B --version
+Display the program name, MCPU toolchain identity and version, then exit.
+.TP
+.B --dump-version
+Display only the MCPU package version number and exit.
+.SH EXIT STATUS
+Zero on success; nonzero on syntax, semantic, I/O or object-generation error.
+.SH EXAMPLES
+.nf
+mcpu-as -o main.o main.s
+mcpu-as helper.s -o helper.o
+.fi
+.SH SEE ALSO
+.BR mcpu-ld (1),
+.BR mcpu-readelf (1),
+.BR mcpu-objdump (1),
+.BR libmcpu (7)