missing realemu manpage

1 files changed, 104 insertions, 0 deletions

diff --git a/sys/man/8/realemu b/sys/man/8/realemu
new file mode 100644
index 000000000..60763b385
--- /dev/null
+++ b/sys/man/8/realemu
@@ -0,0 +1,104 @@
+.TH realemu 8
+.SH NAME
+realemu \- software emulation of /dev/realmode
+.SH SYNOPSIS
+.B aux/realemu
+[
+.B -Dpt
+] [
+.B -s
+.I srvname
+] [
+.B -m
+.I mountpoint
+]
+.SH DESCRIPTION
+.PP
+Originally, kernel provided 
+.B /dev/realmode
+files with the
+.IR arch (3)
+device to access and call the
+.SM BIOS.
+.PP
+Interrupts had to be disabled and the processor was switched in the
+legacy 16-bit
+.SM realmode
+with memory protection disabled to execute
+.SM BIOS
+code.
+.PP
+This is problematic in case the
+.SM BIOS
+reprograms hardware currently
+used by the operating system or when it reenables interrupts or just
+crashes. This will freeze or reboot the machine with no way to
+recover or diagnose the problem.
+.PP
+To avoid this,
+.I realemu
+is used to emulate the execution of the
+.SM BIOS
+routines by interpreting the machine instructions and intercepting
+dangerous actions that would compromise the systems stability.
+.PP
+Running
+.I realemu
+with no arguments, it mounts itself before
+.B /dev
+and
+replaces the original
+.B /dev/realmode
+file in the current namespace.
+.PP
+Then programs like
+.IR vga (8)
+can use it to make ther
+.SM BIOS
+calls.
+.PP
+The
+.B D
+flag will enable debug messages for 9P.  The
+.B p
+and
+.B t
+flags
+control tracing of i/o port access and cpu instructions to
+stderr (fd 2).
+.PP
+When a
+.I srvname
+is given with the
+.B s
+argument, the default
+.I mountpoint
+is ignored and a
+.SM 9P
+channel is created in
+.B /srv
+that can be used to mount
+the filesystem from another namespace. If a
+.I mountpoint
+is given before
+the
+.I srvname
+argument then it is ignored, otherwise it will be used.
+.SH EXAMPLES
+The
+.I realemu
+process is only needed when accessing
+.B /dev/realmode.
+To invoke a subshell so that
+.I realemu
+exits normally after
+.B aux/vga
+completes:
+.IP
+.EX
+% @{rfork n; aux/realemu; aux/vga -m vesa -l $vgasize}
+.SH SOURCE
+.B /sys/src/cmd/aux/realemu
+.SH "SEE ALSO"
+.IR vga (8),
+.IR arch (3)