ref: 645b5f8724c0116d974680bdb591320256cc36e0
parent: c739f57ac2f136e67be63a4678d4171889057105
author: rgl <devnull@localhost>
date: Sat Jan 4 13:02:54 EST 2020
/sys/man/9: more pages added in addition to the pages, there's also changes to the mkfile to generate the index for the new section.
--- /dev/null
+++ b/sys/man/9/inb
@@ -1,0 +1,83 @@
+.TH INB 9
+.SH NAME
+inb, ins, inl, outb, outs, outl, insb, inss, insl, outsb, outss, outsl \- programmed I/O
+.SH SYNOPSIS
+.ta \w'\fLushort 'u
+.B
+int inb(int port)
+.PP
+.B
+ushort ins(int port)
+.PP
+.B
+ulong inl(int port)
+.PP
+.B
+void outb(int port, int value)
+.PP
+.B
+void outs(int port, ushort value)
+.PP
+.B
+void outl(int port, ulong value)
+.PP
+.B
+void insb(int port, void *address, int count)
+.PP
+.B
+void inss(int port, void *address, int count)
+.PP
+.B
+void insl(int port, void *address, int count)
+.PP
+.B
+void outsb(int port, void *address, int count)
+.PP
+.B
+void outss(int port, void *address, int count)
+.PP
+.B
+void outsl(int port, void *address, int count)
+.SH DESCRIPTION
+The
+.I x86
+implementation provides functions to allow kernel code
+written in C to access the I/O address space.
+On several other architectures such as the PowerPC and Strongarm,
+the platform-dependent code provides similar functions to access
+devices with an I/O space interface, even when that is memory mapped, to encourage portability of device drivers.
+.PP
+.IR Inb ,
+.I ins
+and
+.I inl
+apply the corresponding hardware instruction to fetch the next byte, short or long
+from the I/O
+.IR port .
+.IR Outb ,
+.I outs
+and
+.I outl
+output a
+.I value
+to the I/O
+.IR port .
+.PP
+The remaining functions transfer
+.I count
+bytes, shorts, or longs using programmed I/O between a memory
+.I address
+and
+.IR port .
+Functions
+.B insX
+copy values into memory; functions
+.B outsX
+copy values from memory.
+The
+.I count
+is in elements, not bytes.
+.SH SOURCE
+.B /sys/src/9/pc/l.s
+.SH SEE ALSO
+.IR dma (9)
--- /dev/null
+++ b/sys/man/9/parsecmd
@@ -1,0 +1,107 @@
+.TH PARSECMD 9
+.SH NAME
+parsecmd, cmderror, lookupcmd
+\- parse device commands
+.SH SYNOPSIS
+.ta \w'\fLCmdbuf* 'u
+.B
+Cmdbuf* parsecmd(char *a, int n)
+.PP
+.B
+void cmderror(Cmdbuf *cb, char *s)
+.PP
+.B
+Cmdtab* lookupcmd(Cmdbuf *cb, Cmdtab *ctab, int nctab)
+.SH DESCRIPTION
+.I Parsecmd
+is an interface to
+.I tokenize
+(see
+.IR getfields (2)),
+that safely parses a command, with blank-separated fields, as might be
+written to a device's
+.B ctl
+file.
+The buffer
+.I a
+and count
+.I n
+can be those passed to the driver's
+.I write
+function.
+.I Parsecmd
+converts the byte array (which might not be null-terminated) to a null-terminated string,
+trimming any trailing new line,
+before invoking
+.I tokenize
+to break the string into arguments, interpreting blank and tab as field separators
+when they are not quoted
+(in the style of
+.IR rc (1)).
+It returns a pointer to a dynamically-allocated
+.B Cmdbuf
+structure,
+which holds a copy of the string and the resulting fields; it is
+defined as follows:
+.IP
+.EX
+.ta 6n +\w'char* 'u
+typedef
+struct Cmdbuf
+{+ char *buf;
+ char **f;
+ int nf;
+} Cmdbuf;
+.EE
+.PP
+The array
+.B f
+holds the field pointers;
+.B nf
+gives the number of fields.
+.B Cmdbuf
+is allocated by
+.I smalloc
+(see
+.IR malloc (9)),
+and the caller is responsible for freeing it using
+.IR free .
+.I Cmderror
+prepends the given format with the original command,
+then calls
+.IR error (9).
+.PP
+Command strings may be turned into a (typically enumerated)
+integer with
+.IR lookupcmd .
+The catchall
+.L *
+matches any text. Unrecognized commands, or commands
+given an unacceptable number of arguments generate a
+call to
+.IR error .
+The definition is as follows
+.IP
+.EX
+.ta 6n +\w'char* 'u
+typedef
+struct Cmdtab
+{+ int index; /* used by client to switch on result */
+ char *cmd; /* command name */
+ int narg; /* expected #args; 0 ==> variadic */
+} Cmdtab;
+.EE
+.PP
+The integer
+.B index
+is the number returned on command match.
+The string
+.B cmd
+is the command name, and
+.B narg
+is 0 (indicating a variadic function) or the
+number of arguments.
+.SH SOURCE
+.B /sys/src/9/port/parse.c
--- /dev/null
+++ b/sys/man/9/readnum
@@ -1,0 +1,58 @@
+.TH READNUM 9
+.SH NAME
+readnum, readstr \- device read routines
+.SH SYNOPSIS
+.ta \w'\fLint 'u
+.B
+int readstr(ulong off, char *buf, ulong n, char *str)
+.PP
+.B
+int readnum(ulong off, char *buf, ulong n, ulong val, int size)
+.SH DESCRIPTION
+.I Readstr
+and
+.I readnum
+simplify the return of strings and numbers from device
+.I read
+routines,
+because they deal with any buffering and boundary cases.
+Several parameters to the read call are often handed on directly
+to these functions:
+the file offset, as
+.IR off ;
+the address of the user's buffer, as
+.IR buf ;
+and the number of bytes requested, as
+.IR n .
+Both functions return the number of bytes they have stored in
+.IR buf ,
+and which can often be returned directly from the device read routine.
+.PP
+.I Readstr
+satisfies a read by copying data into
+.I buf
+from the NUL-terminated string in
+.IR str .
+The data transferred is selected and limited by
+.IR off ,
+.I n
+and the length of
+.IR str .
+.PP
+.I Readnum
+converts the unsigned integer
+.I val
+to a decimal representation in
+.IR buf .
+The value is right-justified in a field of
+.IR size "-1"
+places and is followed by a blank.
+.I Size
+can be the global constant
+.L NUMSIZE
+for 32-bit integers;
+the largest
+.I size
+allowed is 64 bytes.
+.SH SOURCE
+.B /sys/src/9/port/devcons.c
--- /dev/null
+++ b/sys/man/9/sched
@@ -1,0 +1,89 @@
+.TH SCHED 9
+.SH NAME
+anyhigher, anyready, hzsched, procpriority, procrestore, procsave, scheddump, schedinit, sched, yield
+\– scheduler interactions
+.SH SYNOPSIS
+.ta \w'\fLchar* 'u +10n +8n +8n
+.EX
+int anyhigher(void)
+int anyready(void)
+void hzsched(void)
+void procpriority(Proc *p, int priority, int fixed)
+void procrestore(Proc *p)
+void procsave(Proc *p)
+void procwired(Proc *p, int machno)
+void scheddump(void)
+void schedinit(void)
+void sched(void)
+void yield(void)
+
+enum {+...
+ Npriq = 20, /* scheduler priority levels */
+ PriNormal = 10, /* base for normal processes */
+ PriKproc = 13, /* base for kernel processes */
+ PriRoot = 13, /* base for root processes */
+};
+.EE
+.SH DESCRIPTION
+.PP
+These functions define the priority process scheduler's interface.
+Processes are scheduled strictly by priority, and processor affinity.
+When possible, processes with no affinity will be rescheduled on the
+same processor. Within a priority, scheduling is round–robin.
+Long–running processes of the same priority are preempted and
+rescheduled. But cpu use (or lack thereof) may adjust the priority up
+or down, unless it has been explicitly fixed. Kernel processes are
+started with
+.B PriKproc
+while user processes start with
+.BR PriNormal .
+.PP
+.I Anyhigher
+returns true if any higher priority processes are runnable, while
+.I anyready
+returns true if any processes are runnable at all.
+.I Yield
+gives up the processor and pretends to consume ½ clock tick, while
+.I sched
+invokes the scheduler, potentially recursively.
+.I Sched
+may be called outside process context. Either may return immediately.
+.I Schedinit
+initializes scheduling on the running processor.
+.PP
+.I Procpriority
+sets a process' priority directly. Fixed–priority processes are not
+reprioritized based on cpu use.
+.I Procwired
+makes a process runnable only on a single processor.
+.PP
+.I Hzsched
+is called by the clock routine on every tick to collect statistics.
+Periodically (typically once a second)
+.I hzsched
+reprioritizes based on cpu use.
+.PP
+.I Procsave
+and
+.I procrestore
+are architecture–dependent routines used by the scheduler to save and
+restore processes.
+.I Scheddump
+prints scheduler statistics.
+.SH SOURCE
+.B /sys/src/9/port/proc.c
+.sp 0.3
+.I Procsave
+and
+.I procrestore
+can be found at
+.br
+.B /sys/src/9/*/main.c
+.br
+.B /sys/src/9/*/arch.c
+.br
+.B /sys/src/9/*/trap.c
+.SH SEE ALSO
+.IR edf (9),
+.IR sleep (9)
--- /dev/null
+++ b/sys/man/9/seconds
@@ -1,0 +1,75 @@
+.TH SECONDS 9
+.SH NAME
+seconds, ticks, fastticks, HZ, MS2HZ, MS2TK, TK2MS, TK2SEC \- kernel times and time conversions
+.SH SYNOPSIS
+.ta \w'\fL#define 'u
+.B
+long seconds(void)
+.PP
+.B
+vlong fastticks(uvlong *hz)
+.PP
+.EX
+#define HZ ...
+#define MS2HZ (1000/HZ)
+#define TK2SEC(t) ((t)/HZ)
+#define TK2MS(t) ((t)*(1000/HZ))
+.EE
+.SH DESCRIPTION
+.I Seconds
+returns the system's idea of the current time as the number of seconds
+since the start of the epoch
+(00:00:00 GMT, January 1, 1970).
+.PP
+The
+.B ticks
+field of the
+.B Mach
+structure returns the number of system-dependent clock ticks on the
+given processor since system boot.
+On a multiprocessor,
+.B MACHP(0)
+is sometimes used to provide a reference time, since the tick value
+might vary slightly across processors.
+.PP
+.I Fastticks
+returns the number of ticks since boot as measured by the
+fastest clock provided by the platform.
+The frequency of the clock, in ticks per second,
+is returned through
+.IR hz ,
+unless it is nil.
+.PP
+The system clock frequencies are platform-dependent.
+Several symbolic constants and macro functions are defined by
+the file
+.B mem.h
+to convert between different time units:
+.TF TK2SEC(t)
+.PD
+.TP
+.B HZ
+The number of clock ticks per second.
+.TP
+.B MS2HZ
+Milliseconds per clock tick.
+.TP
+.BI TK2SEC( t )
+Convert
+.I t
+clock ticks to seconds (truncating not rounding).
+.TP
+.BI TK2MS( t )
+Convert
+.I t
+clock ticks to milliseconds.
+.SH SOURCE
+.B /sys/src/9/*/mem.h
+.br
+.B /sys/src/9/*/clock.c
+.br
+.B /sys/src/9/*/devarch.c
+.br
+.B /sys/src/9/*/timer.c
+.br
+.B /sys/src/9/port/tod.c
--- a/sys/man/mkfile
+++ b/sys/man/mkfile
@@ -5,7 +5,7 @@
default:V: check
indices:V:
- for (i in [0-8]){+ for (i in [0-9]){$LIB/secindex $i > $i/INDEX
$LIB/mkhtmlindex $i > $i/INDEX.html
}
@@ -18,7 +18,7 @@
echo .am TH
echo .tm '\\$1' '\\$2' '\\n%'
echo ..
- for (i in [0-8]){+ for (i in [0-9]){builtin cd $i
for(j in [a-z0-9]*)
switch($i/$j){@@ -41,18 +41,18 @@
mk out > /dev/null >[2] /dev/null
old-check:V: checksource
- awk -f $LIB/checkman.awk [0-8]/* | sed '/\/(cda|av|midi|pub|weather|service\.9net|isdn)(\/|\))/d'
+ awk -f $LIB/checkman.awk [0-9]/* | sed '/\/(cda|av|midi|pub|weather|service\.9net|isdn)(\/|\))/d'
punccheck:
grep -n '^\.[IB][^PRIB].+[.;,:]$' [0-9]/* | grep -v '\.\.\.'
check:V: indices checksource
- awk -f $LIB/checkman.awk [0-8]/*
+ awk -f $LIB/checkman.awk [0-9]/*
checksource:QV:
sam -d >[2]/dev/null <<'!'
f input
- < cat [0-8]/[0-9a-z]*
+ < cat [0-9]/[0-9a-z]*
B output
b input
,x/^\.SH SOURCE/ .,/^\.SH/ x g/^\.B/t "output
@@ -80,7 +80,7 @@
{echo -n $FONTS; cat $LIB/preface} | troff -ms {echo -n $FONTS; echo ' '} | troff {- for (i in [0-8]){+ for (i in [0-9]){builtin cd $i
for(j in [a-z0-9]*)
switch($i/$j){@@ -116,6 +116,6 @@
ps2pdf $prereq $target
clean:V:
- rm -f man.out print.out searchindex $LIB/permind/toc $LIB/lookman/index [0-8]^/INDEX^('' .html)+ rm -f man.out print.out searchindex $LIB/permind/toc $LIB/lookman/index [0-9]^/INDEX^('' .html)builtin cd $LIB/permind
mk clean