Import sources from 2011-03-30 iso image - sys/man

1 files changed, 170 insertions, 0 deletions

diff --git a/sys/man/1/vi b/sys/man/1/vi
new file mode 100755
index 000000000..1adf8d209
--- /dev/null
+++ b/sys/man/1/vi
@@ -0,0 +1,170 @@
+.TH VI 1
+.SH NAME
+5i, ki, vi, qi \- instruction simulators
+.SH SYNOPSIS
+.B vi
+[
+.I textfile
+]
+.br
+.B vi
+.I pid
+.br
+.B 5i
+[
+.I textfile
+]
+.br
+.B 5i
+.I pid
+.br
+.B ki
+[
+.I textfile
+]
+.br
+.B ki
+.I pid
+.br
+.B qi
+[
+.I textfile
+]
+.br
+.B qi
+.I pid
+.SH DESCRIPTION
+.I Vi
+simulates the execution of a MIPS binary in
+a Plan 9 environment.
+It has two main uses: as
+a debugger and as a statistics gatherer.
+Programs running under
+.I vi
+execute about two hundred times
+slower than normal\(embut faster than
+single stepping under
+.IR db .
+.IR 5i ,
+.IR ki ,
+and
+.IR qi
+are similar to
+.I vi
+but interpret ARM, SPARC, and PowerPC binaries.
+The following discussion refers to
+.I vi
+but applies to the others
+as well.
+.PP
+.I Vi
+will simulate the execution of a named
+.IR textfile .
+It will also make a copy of an existing process with process id
+.I pid
+and simulate its continuation.
+.PP
+As a debugger
+.I vi
+offers more complete information
+than
+.IR db (1).
+Tracing can be performed at the level of instructions,
+system calls, or function calls.
+.I Vi
+allows breakpoints to be triggered when specified addresses
+in memory are accessed.
+A report of instruction counts,
+load delay fills and distribution is produced for
+each run.
+.I Vi
+simulates the CPU's caches and MMU
+to assist the optimization of compilers and programs.
+.PP
+The command interface mirrors the interface to
+.IR db ;
+see
+.IR db (1)
+for a detailed description.
+Data formats and addressing are compatible with
+.I db
+except
+for disassembly: 
+.I vi
+offers only MIPS
+.RB ( db
+.BR -mmipsco )
+mnemonics for
+machine instructions.
+.I Ki
+offers both Plan 9 and Sun SPARC formats.
+.PP
+Several extra commands allow
+extended tracing and printing of statistics:
+.TP
+.BR $t [ 0ics ]
+The
+.I t
+command controls tracing. Zero cancels all tracing
+options.
+.RS
+.TP
+.B i
+Enable instruction tracing
+.TP
+.B c
+Enable call tracing
+.TP
+.B s
+Enable system call tracing
+.RE
+.TP
+.BR $i [ itsp ]
+The
+.B i
+command prints statistics accumulated by
+all code run in this session.
+.RS
+.TP
+.B i
+Print instruction counts and frequency.
+.TP
+.B p
+Print cycle profile.
+.TP
+.B t
+.RI ( Vi
+only) Print TLB and cache statistics.
+.TP
+.B s
+Print memory reference, working set and size statistics.
+.RE
+.TP
+.BR :b [ arwe ]
+.I Vi
+allows breakpoints to be set on any memory location.
+These breakpoints monitor when a location is
+accessed, read, written, or equals a certain value.
+For equality the compared value is the
+.I count
+(see
+.IR db (1))
+supplied to the command.
+.SH SOURCE
+.B /sys/src/cmd/vi
+etc.
+.SH "SEE ALSO"
+.IR nm (1),
+.IR db (1)
+.SH BUGS
+The code generated by
+the compilers
+is well supported, but some unusual instructions are unimplemented.
+Some Plan 9 system calls such as
+.I rfork
+cause simulated traps.
+The floating point simulation makes assumptions about the interpreting
+machine's floating point support. The floating point conversions performed
+by
+.I vi
+may cause a loss of precision.