add start of section 9 manpages (thanks rgl)
this change adds some of the kernel manpages from 9legacy, fixed and updated to match the changes in 9front.
This commit is contained in:
Ori Bernstein
parent
37d6ddd8f3
commit
0b6f0c70db
15 changed files with 1639 additions and 0 deletions
53
sys/man/9/0intro
Normal file
53
sys/man/9/0intro
Normal file
|
|
@ -0,0 +1,53 @@
|
||||||
|
.TH INTRO 9
|
||||||
|
.SH NAME
|
||||||
|
intro \- introduction to kernel functions
|
||||||
|
.SH DESCRIPTION
|
||||||
|
This section of the manual
|
||||||
|
describes the functions publicly available to the authors of
|
||||||
|
kernel code, particularly device drivers (real and virtual).
|
||||||
|
This section will eventually be much expanded, but this makes a start.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.SM SYNOPSIS
|
||||||
|
subsections do not show the header files needed for
|
||||||
|
the standard kernel declarations.
|
||||||
|
The primary combinations summarised below:
|
||||||
|
.IP
|
||||||
|
.RS
|
||||||
|
.ta \w'\fL#include 'u
|
||||||
|
.nf
|
||||||
|
.B
|
||||||
|
#include "u.h"
|
||||||
|
.B
|
||||||
|
#include "../port/lib.h"
|
||||||
|
.B
|
||||||
|
#include "mem.h"
|
||||||
|
.B
|
||||||
|
#include "dat.h"
|
||||||
|
.B
|
||||||
|
#include "fns.h"
|
||||||
|
.B
|
||||||
|
#include "../port/error.h"
|
||||||
|
.PP
|
||||||
|
.I "furthermore, added in IP code:"
|
||||||
|
.br
|
||||||
|
.B
|
||||||
|
#include "../ip/ip.h"
|
||||||
|
.PP
|
||||||
|
.I "furthermore, in hardware device drivers:"
|
||||||
|
.br
|
||||||
|
.B
|
||||||
|
#include "io.h"
|
||||||
|
.br
|
||||||
|
.B
|
||||||
|
#include "ureg.h"
|
||||||
|
.PP
|
||||||
|
.I "furthermore, in network interfaces or ether drivers:"
|
||||||
|
.B
|
||||||
|
#include "../port/netif.h"
|
||||||
|
.fi
|
||||||
|
.RE
|
||||||
|
.PP
|
||||||
|
There might also be specific include files needed by
|
||||||
|
drivers on particular platforms or to use specialised kernel interfaces.
|
||||||
|
The easiest method is to check the source of likely-looking drivers nearby.
|
||||||
67
sys/man/9/INDEX
Normal file
67
sys/man/9/INDEX
Normal file
|
|
@ -0,0 +1,67 @@
|
||||||
|
0intro 0intro
|
||||||
|
intro 0intro
|
||||||
|
BALLOC allocb
|
||||||
|
BLEN allocb
|
||||||
|
adjustblock allocb
|
||||||
|
allocb allocb
|
||||||
|
blockalloclen allocb
|
||||||
|
blocklen allocb
|
||||||
|
checkb allocb
|
||||||
|
concatblock allocb
|
||||||
|
copyblock allocb
|
||||||
|
freeb allocb
|
||||||
|
freeblist allocb
|
||||||
|
iallocb allocb
|
||||||
|
packblock allocb
|
||||||
|
padblock allocb
|
||||||
|
pullblock allocb
|
||||||
|
pullupblock allocb
|
||||||
|
readblist allocb
|
||||||
|
trimblock allocb
|
||||||
|
addclock0link delay
|
||||||
|
delay delay
|
||||||
|
microdelay delay
|
||||||
|
error error
|
||||||
|
nexterror error
|
||||||
|
poperror error
|
||||||
|
waserror error
|
||||||
|
eve eve
|
||||||
|
iseve eve
|
||||||
|
intrdisable intrenable
|
||||||
|
intrenable intrenable
|
||||||
|
kproc kproc
|
||||||
|
pexit kproc
|
||||||
|
postnote kproc
|
||||||
|
free malloc
|
||||||
|
getmalloctag malloc
|
||||||
|
getrealloctag malloc
|
||||||
|
malloc malloc
|
||||||
|
mallocz malloc
|
||||||
|
msize malloc
|
||||||
|
realloc malloc
|
||||||
|
secalloc malloc
|
||||||
|
secfree malloc
|
||||||
|
setmalloctag malloc
|
||||||
|
setrealloctag malloc
|
||||||
|
smalloc malloc
|
||||||
|
panic panic
|
||||||
|
canqlock qlock
|
||||||
|
qlock qlock
|
||||||
|
qunlock qlock
|
||||||
|
rlock qlock
|
||||||
|
runlock qlock
|
||||||
|
wlock qlock
|
||||||
|
wunlock qlock
|
||||||
|
return0 sleep
|
||||||
|
sleep sleep
|
||||||
|
tsleep sleep
|
||||||
|
wakeup sleep
|
||||||
|
islo splhi
|
||||||
|
splhi splhi
|
||||||
|
spllo splhi
|
||||||
|
splx splhi
|
||||||
|
xalloc xalloc
|
||||||
|
xallocz xalloc
|
||||||
|
xfree xalloc
|
||||||
|
xspanalloc xalloc
|
||||||
|
xsummary xalloc
|
||||||
61
sys/man/9/INDEX.html
Normal file
61
sys/man/9/INDEX.html
Normal file
|
|
@ -0,0 +1,61 @@
|
||||||
|
<HEAD>
|
||||||
|
<TITLE>plan 9 man section 9</TITLE>
|
||||||
|
</HEAD>
|
||||||
|
<BODY>
|
||||||
|
<B>[<A HREF="/sys/man/index.html">manual index</A>]</B>
|
||||||
|
<H2>Plan 9 from Bell Labs - Section 9 - </H2>
|
||||||
|
<HR>
|
||||||
|
<DL>
|
||||||
|
<DT><A HREF="/magic/man2html/9/0intro">0intro</A>
|
||||||
|
- introduction to kernel functions
|
||||||
|
<DD><TT> intro</TT>
|
||||||
|
</DT>
|
||||||
|
<DT><A HREF="/magic/man2html/9/allocb">allocb</A>
|
||||||
|
- data block management
|
||||||
|
<DD><TT> allocb, iallocb, freeb, freeblist, BLEN, BALLOC, blocklen, blockalloclen, readblist, concatblock, copyblock, trimblock, packblock, padblock, pullblock, pullupblock, adjustblock, checkb</TT>
|
||||||
|
</DT>
|
||||||
|
<DT><A HREF="/magic/man2html/9/delay">delay</A>
|
||||||
|
- small delays, clock interrupts
|
||||||
|
<DD><TT> delay, microdelay, addclock0link</TT>
|
||||||
|
</DT>
|
||||||
|
<DT><A HREF="/magic/man2html/9/error">error</A>
|
||||||
|
- error handling functions
|
||||||
|
<DD><TT> error, nexterror, poperror, waserror</TT>
|
||||||
|
</DT>
|
||||||
|
<DT><A HREF="/magic/man2html/9/eve">eve</A>
|
||||||
|
- privileged user
|
||||||
|
<DD><TT> eve, iseve</TT>
|
||||||
|
</DT>
|
||||||
|
<DT><A HREF="/magic/man2html/9/intrenable">intrenable</A>
|
||||||
|
- enable (disable) an interrupt handler
|
||||||
|
<DD><TT> intrenable, intrdisable</TT>
|
||||||
|
</DT>
|
||||||
|
<DT><A HREF="/magic/man2html/9/kproc">kproc</A>
|
||||||
|
- kernel process creation, termination and interruption
|
||||||
|
<DD><TT> kproc, pexit, postnote</TT>
|
||||||
|
</DT>
|
||||||
|
<DT><A HREF="/magic/man2html/9/malloc">malloc</A>
|
||||||
|
- kernel memory allocator
|
||||||
|
<DD><TT> malloc, mallocz, smalloc, realloc, free, msize, secalloc, secfree, setmalloctag, setrealloctag, getmalloctag, getrealloctag</TT>
|
||||||
|
</DT>
|
||||||
|
<DT><A HREF="/magic/man2html/9/panic">panic</A>
|
||||||
|
- abandon hope, all ye who enter here
|
||||||
|
<DD><TT> panic</TT>
|
||||||
|
</DT>
|
||||||
|
<DT><A HREF="/magic/man2html/9/qlock">qlock</A>
|
||||||
|
- serial synchronisation
|
||||||
|
<DD><TT> qlock, qunlock, canqlock, rlock, runlock, wlock, wunlock</TT>
|
||||||
|
</DT>
|
||||||
|
<DT><A HREF="/magic/man2html/9/sleep">sleep</A>
|
||||||
|
- process synchronisation
|
||||||
|
<DD><TT> sleep, wakeup, tsleep, return0</TT>
|
||||||
|
</DT>
|
||||||
|
<DT><A HREF="/magic/man2html/9/splhi">splhi</A>
|
||||||
|
- enable and disable interrupts
|
||||||
|
<DD><TT> splhi, spllo, splx, islo</TT>
|
||||||
|
</DT>
|
||||||
|
<DT><A HREF="/magic/man2html/9/xalloc">xalloc</A>
|
||||||
|
- basic memory management
|
||||||
|
<DD><TT> xalloc, xallocz, xspanalloc, xfree, xsummary</TT>
|
||||||
|
</DT>
|
||||||
|
</DL>
|
||||||
343
sys/man/9/allocb
Normal file
343
sys/man/9/allocb
Normal file
|
|
@ -0,0 +1,343 @@
|
||||||
|
.TH ALLOCB 9
|
||||||
|
.SH NAME
|
||||||
|
allocb, iallocb, freeb, freeblist, BLEN, BALLOC, blocklen, blockalloclen, readblist, concatblock, copyblock, trimblock, packblock, padblock, pullblock, pullupblock, adjustblock, checkb \- data block management
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.ta \w'\fLBlock* 'u
|
||||||
|
.B
|
||||||
|
Block* allocb(int size)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
Block* iallocb(int size)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void freeb(Block *b)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void freeblist(Block *b)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
int blocklen(Block *b)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
int blockalloclen(Block *b)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
long readblist(Block *b, uchar *p, long n, ulong offset)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
Block* concatblock(Block *b)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
Block* copyblock(Block *b, int n)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
Block* trimblock(Block *b, int offset, int n)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
Block* packblock(Block *b)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
Block* padblock(Block *b, int n)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
int pullblock(Block **bph, int n)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
Block* pullupblock(Block *b, int n)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
Block* adjustblock(Block *b, int n)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void checkb(Block *b, char *msg)
|
||||||
|
.sp 0.1
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
#define BLEN(s) ((s)->wp - (s)->rp)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
#define BALLOC(s) ((s)->lim - (s)->base)
|
||||||
|
.SH DESCRIPTION
|
||||||
|
A
|
||||||
|
.B Block
|
||||||
|
provides a receptacle for data:
|
||||||
|
.IP
|
||||||
|
.EX
|
||||||
|
.DT
|
||||||
|
typedef
|
||||||
|
struct Block
|
||||||
|
{
|
||||||
|
Block* next;
|
||||||
|
Block* list;
|
||||||
|
uchar* rp; /* first unconsumed byte */
|
||||||
|
uchar* wp; /* first empty byte */
|
||||||
|
uchar* lim; /* 1 past the end of the buffer */
|
||||||
|
uchar* base; /* start of the buffer */
|
||||||
|
void (*free)(Block*);
|
||||||
|
ushort flag;
|
||||||
|
ushort checksum; /* IP checksum of complete packet */
|
||||||
|
} Block;
|
||||||
|
.EE
|
||||||
|
.PP
|
||||||
|
Each
|
||||||
|
.B Block
|
||||||
|
has an associated buffer, located at
|
||||||
|
.BR base ,
|
||||||
|
and accessed via
|
||||||
|
.B wp
|
||||||
|
when filling the buffer, or
|
||||||
|
.B rp
|
||||||
|
when fetching data from it.
|
||||||
|
Each pointer should be incremented to reflect the amount of data written or read.
|
||||||
|
A
|
||||||
|
.B Block
|
||||||
|
is empty when
|
||||||
|
.B rp
|
||||||
|
reaches
|
||||||
|
.BR wp .
|
||||||
|
The pointer
|
||||||
|
.B lim
|
||||||
|
bounds the allocated space.
|
||||||
|
Some operations described below accept lists of
|
||||||
|
.BR Block s,
|
||||||
|
which are
|
||||||
|
chained via their
|
||||||
|
.B next
|
||||||
|
pointers, with a null pointer ending the list.
|
||||||
|
.B Blocks
|
||||||
|
are usually intended for a
|
||||||
|
.B Queue
|
||||||
|
(see
|
||||||
|
.IR qio (9)),
|
||||||
|
but can be used independently.
|
||||||
|
.PP
|
||||||
|
A
|
||||||
|
.B Block
|
||||||
|
and its buffer are normally allocated by one call to
|
||||||
|
.IR malloc (9)
|
||||||
|
and aligned on an 8 byte (\fLBY2V\fP) boundary.
|
||||||
|
Some devices with particular allocation constraints
|
||||||
|
(eg, requiring certain addresses for DMA) might allocate their own
|
||||||
|
.B Block
|
||||||
|
and buffer;
|
||||||
|
.B free
|
||||||
|
must then point to a function that can deallocate the specially allocated
|
||||||
|
.BR Block .
|
||||||
|
.PP
|
||||||
|
Many
|
||||||
|
.B Block
|
||||||
|
operations cannot be used in interrupt handlers
|
||||||
|
because they either
|
||||||
|
.IR sleep (9)
|
||||||
|
or raise an
|
||||||
|
.IR error (9).
|
||||||
|
Of operations that allocate blocks, only
|
||||||
|
.IR iallocb
|
||||||
|
is usable.
|
||||||
|
.PP
|
||||||
|
.I Allocb
|
||||||
|
allocates a
|
||||||
|
.B Block
|
||||||
|
of at least
|
||||||
|
.IR size
|
||||||
|
bytes.
|
||||||
|
The block
|
||||||
|
is initially empty:
|
||||||
|
.B rp
|
||||||
|
and
|
||||||
|
.B wp
|
||||||
|
point to the start of the data.
|
||||||
|
If it cannot allocate memory,
|
||||||
|
.I allocb
|
||||||
|
raises an
|
||||||
|
.IR error (9);
|
||||||
|
it cannot be used by an interrupt handler.
|
||||||
|
.PP
|
||||||
|
.IR Iallocb
|
||||||
|
is similar to
|
||||||
|
.IR allocb
|
||||||
|
but is intended for use by interrupt handlers,
|
||||||
|
and returns a null pointer if no memory is available.
|
||||||
|
It also limits its allocation to a quota allocated at system initialisation to interrupt-time buffering.
|
||||||
|
.PP
|
||||||
|
.I Freeb
|
||||||
|
frees a single
|
||||||
|
.B Block
|
||||||
|
(and its buffer).
|
||||||
|
.PP
|
||||||
|
.I Freeblist
|
||||||
|
frees the whole
|
||||||
|
list of blocks headed by
|
||||||
|
.IR b .
|
||||||
|
.PP
|
||||||
|
.I BLEN
|
||||||
|
returns the number of unread bytes in a single block.
|
||||||
|
.PP
|
||||||
|
.I BALLOC
|
||||||
|
returns the number of allocated bytes in a single block.
|
||||||
|
.PP
|
||||||
|
.I Blocklen
|
||||||
|
returns the number of bytes of unread data in the whole list of blocks headed by
|
||||||
|
.IR b .
|
||||||
|
.PP
|
||||||
|
.I Blockalloclen
|
||||||
|
returns the number of total bytes allocated in the whole list of blocks headed by
|
||||||
|
.IR b .
|
||||||
|
.PP
|
||||||
|
.I Readblist
|
||||||
|
copies
|
||||||
|
.I n
|
||||||
|
bytes of data at offset
|
||||||
|
.I offset
|
||||||
|
from the list of blocks headed by
|
||||||
|
.I b
|
||||||
|
into
|
||||||
|
.IR p ,
|
||||||
|
then returns the amount of bytes copied. It leaves the block list intact.
|
||||||
|
.PP
|
||||||
|
.I Concatblock
|
||||||
|
returns
|
||||||
|
.I b
|
||||||
|
if it is not a list, and otherwise
|
||||||
|
returns a single
|
||||||
|
.B Block
|
||||||
|
containing all the data in the list of blocks
|
||||||
|
.IR b ,
|
||||||
|
which it frees.
|
||||||
|
.PP
|
||||||
|
.I Copyblock
|
||||||
|
by contrast returns a single
|
||||||
|
.B Block
|
||||||
|
containing a copy of the first
|
||||||
|
.I n
|
||||||
|
bytes of data in the block list
|
||||||
|
.IR b ,
|
||||||
|
padding with zeroes if the list contained less than
|
||||||
|
.I n
|
||||||
|
bytes.
|
||||||
|
The list
|
||||||
|
.I b
|
||||||
|
is unchanged.
|
||||||
|
.PP
|
||||||
|
.I Padblock
|
||||||
|
can pad a single
|
||||||
|
.B Block
|
||||||
|
at either end, to reserve space for protocol headers or trailers.
|
||||||
|
If
|
||||||
|
.IR n ≥ 0 ,
|
||||||
|
it inserts
|
||||||
|
.I n
|
||||||
|
bytes at the start of the block,
|
||||||
|
setting the read pointer
|
||||||
|
.B rp
|
||||||
|
to point to the new space.
|
||||||
|
If
|
||||||
|
.IR n < 0 ,
|
||||||
|
it adds
|
||||||
|
.I n
|
||||||
|
bytes at the end of the block,
|
||||||
|
leaving the write pointer
|
||||||
|
.B wp
|
||||||
|
pointing at the new space.
|
||||||
|
In both cases, it allocates a new
|
||||||
|
.B Block
|
||||||
|
if necessary, freeing the old, and
|
||||||
|
it always returns a pointer to the resulting
|
||||||
|
.BR Block .
|
||||||
|
.PP
|
||||||
|
.I Trimblock
|
||||||
|
trims the list
|
||||||
|
.I b
|
||||||
|
to contain no more than
|
||||||
|
.I n
|
||||||
|
bytes starting at
|
||||||
|
.I offset
|
||||||
|
bytes into the data of the original list.
|
||||||
|
It returns a new list, freeing unneeded parts of the old.
|
||||||
|
If no data remains, it returns a null pointer.
|
||||||
|
.PP
|
||||||
|
.I Packblock
|
||||||
|
examines each
|
||||||
|
.B Block
|
||||||
|
in the list
|
||||||
|
.IR b ,
|
||||||
|
reallocating any block in the list that has four times more available space than actual data.
|
||||||
|
It returns a pointer to the revised list.
|
||||||
|
.PP
|
||||||
|
.I Pullblock
|
||||||
|
discards up to
|
||||||
|
.I n
|
||||||
|
bytes from the start of the list headed by
|
||||||
|
.BI * bph \f1.\f0
|
||||||
|
Unneeded blocks are freed.
|
||||||
|
.I Pullblock
|
||||||
|
sets
|
||||||
|
.BI * bph
|
||||||
|
to point to the new list head
|
||||||
|
and returns the number of bytes discarded (which might be less than
|
||||||
|
.IR n ).
|
||||||
|
It is used by transport protocols to discard ack'd data at
|
||||||
|
the head of a retransmission queue.
|
||||||
|
.PP
|
||||||
|
.I Pullupblock
|
||||||
|
rearranges the data in the list of blocks
|
||||||
|
.I b
|
||||||
|
to ensure that there are at least
|
||||||
|
.I n
|
||||||
|
bytes of contiguous data in the first block,
|
||||||
|
and returns a pointer to the new list head.
|
||||||
|
It frees any blocks that it empties.
|
||||||
|
It returns a null pointer if there is not enough data in the list.
|
||||||
|
.PP
|
||||||
|
.I Adjustblock
|
||||||
|
ensures that the block
|
||||||
|
.I b
|
||||||
|
has at least
|
||||||
|
.I n
|
||||||
|
bytes of data, reallocating or padding with zero if necessary.
|
||||||
|
It returns a pointer to the new
|
||||||
|
.BR Block .
|
||||||
|
(If
|
||||||
|
.I n
|
||||||
|
is negative, it frees the block and returns a null pointer.)
|
||||||
|
.PP
|
||||||
|
.I Checkb
|
||||||
|
does some consistency checking of
|
||||||
|
the state of
|
||||||
|
.IR b ;
|
||||||
|
a
|
||||||
|
.IR panic (9)
|
||||||
|
results if things look grim.
|
||||||
|
It is intended for internal use by the queue I/O routines (see
|
||||||
|
.IR qio (9))
|
||||||
|
but could be used elsewhere.
|
||||||
|
.PP
|
||||||
|
The only functions that can be called at interrupt level are
|
||||||
|
.IR iallocb ,
|
||||||
|
.IR freeb ,
|
||||||
|
.IR freeblist ,
|
||||||
|
.IR BLEN ,
|
||||||
|
.IR BALLOC ,
|
||||||
|
.IR blocklen ,
|
||||||
|
.IR blockalloclen ,
|
||||||
|
.IR readblist
|
||||||
|
and
|
||||||
|
.IR trimblock .
|
||||||
|
The others allocate memory and can potentially block.
|
||||||
|
.SH SOURCE
|
||||||
|
.B /sys/src/9/port/allocb.c
|
||||||
|
.br
|
||||||
|
.B /sys/src/9/port/qio.c
|
||||||
|
.SH DIAGNOSTICS
|
||||||
|
Many functions directly or indirectly can raise an
|
||||||
|
.IR error (9),
|
||||||
|
and callers must therefore provide for proper error recovery
|
||||||
|
as described therein to prevent memory leaks and other bugs.
|
||||||
|
Except for
|
||||||
|
.IR iallocb ,
|
||||||
|
any functions that allocate new blocks or lists
|
||||||
|
are unsuitable for use by interrupt handlers.
|
||||||
|
.IR Iallocb
|
||||||
|
returns a null pointer when it runs out of memory.
|
||||||
|
.SH SEE ALSO
|
||||||
|
.IR qio (9)
|
||||||
46
sys/man/9/delay
Normal file
46
sys/man/9/delay
Normal file
|
|
@ -0,0 +1,46 @@
|
||||||
|
.TH DELAY 9
|
||||||
|
.SH NAME
|
||||||
|
delay, microdelay, addclock0link \- small delays, clock interrupts
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.ta \w'\fLTimer* 'u
|
||||||
|
.B
|
||||||
|
void delay(int ms)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void microdelay(int µs)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
Timer* addclock0link(void(*clockf)(void), int ms)
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.I Delay
|
||||||
|
busy waits for
|
||||||
|
.I ms
|
||||||
|
milliseconds, forced to be at least one millisecond on some architectures.
|
||||||
|
.PP
|
||||||
|
.I Microdelay
|
||||||
|
works exactly the same as
|
||||||
|
.I delay
|
||||||
|
but using microseconds instead.
|
||||||
|
.PP
|
||||||
|
For delays on the order of clock ticks,
|
||||||
|
.I tsleep
|
||||||
|
(see
|
||||||
|
.IR sleep (9))
|
||||||
|
provides a better alternative to the busy waiting of these routines.
|
||||||
|
.PP
|
||||||
|
.I Addclock0link
|
||||||
|
adds a new periodic timer to the current processor's timer list, with
|
||||||
|
.I clockf
|
||||||
|
executing every
|
||||||
|
.I ms
|
||||||
|
milliseconds. If
|
||||||
|
.I ms
|
||||||
|
is zero a default clock is used, it will panic otherwise (i.e.
|
||||||
|
.I ms
|
||||||
|
< 0).
|
||||||
|
.SH SOURCE
|
||||||
|
.B /sys/src/9/port/portclock.c
|
||||||
|
.br
|
||||||
|
.B /sys/src/9/*/clock.c
|
||||||
|
.SH SEE ALSO
|
||||||
|
.IR sleep (9)
|
||||||
171
sys/man/9/error
Normal file
171
sys/man/9/error
Normal file
|
|
@ -0,0 +1,171 @@
|
||||||
|
.TH ERROR 9
|
||||||
|
.SH NAME
|
||||||
|
error, nexterror, poperror, waserror \- error handling functions
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.ta \w'\fL#define 'u
|
||||||
|
.B
|
||||||
|
void error(char*)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void nexterror(void)
|
||||||
|
.sp 0.1
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
#define poperror() (up->nerrlab--)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
#define waserror() (setlabel(&up->errlab[up->nerrlab++]))
|
||||||
|
.SH DESCRIPTION
|
||||||
|
The kernel handles error conditions using non-local gotos,
|
||||||
|
similar to
|
||||||
|
.IR setjmp (2),
|
||||||
|
but using a stack of error labels to implement nested exception handling.
|
||||||
|
This simplifies many of the internal interfaces by eliminating the need
|
||||||
|
for returning and checking error codes at every level of the call stack,
|
||||||
|
at the cost of requiring kernel routines to adhere to a strict discipline.
|
||||||
|
.PP
|
||||||
|
Each process has in its defining kernel
|
||||||
|
.B Proc
|
||||||
|
structure a stack of labels,
|
||||||
|
.B NERR
|
||||||
|
(currently 64) elements deep.
|
||||||
|
A kernel function that must perform a clean up or recovery action on an error
|
||||||
|
makes a stylised call to
|
||||||
|
.IR waserror ,
|
||||||
|
.IR nexterror
|
||||||
|
and
|
||||||
|
.IR poperror :
|
||||||
|
.IP
|
||||||
|
.EX
|
||||||
|
.DT
|
||||||
|
if(waserror()){
|
||||||
|
/* recovery action */
|
||||||
|
nexterror();
|
||||||
|
}
|
||||||
|
/* normal action */
|
||||||
|
poperror();
|
||||||
|
.EE
|
||||||
|
.PP
|
||||||
|
When called in the normal course of events,
|
||||||
|
.I waserror
|
||||||
|
registers an error handling block by pushing its label onto the stack,
|
||||||
|
and returns zero.
|
||||||
|
The return value of
|
||||||
|
.I waserror
|
||||||
|
should be tested as shown above.
|
||||||
|
If non-zero (true), the calling function should perform the needed
|
||||||
|
error recovery, ended by a call to
|
||||||
|
.I nexterror
|
||||||
|
to transfer control to the next location on the error stack.
|
||||||
|
Typical recovery actions include deallocating memory, unlocking resources, and
|
||||||
|
resetting state variables.
|
||||||
|
.PP
|
||||||
|
Within the recovery block,
|
||||||
|
after handling an error condition, there must normally
|
||||||
|
be a call to
|
||||||
|
.I nexterror
|
||||||
|
to transfer control to any error recovery lower down in the stack.
|
||||||
|
The main exception is in the outermost function in a process,
|
||||||
|
which must not call
|
||||||
|
.I nexterror
|
||||||
|
(there being nothing further on the stack), but calls
|
||||||
|
.I pexit
|
||||||
|
(see
|
||||||
|
.IR kproc (9))
|
||||||
|
instead,
|
||||||
|
to terminate the process.
|
||||||
|
.PP
|
||||||
|
When the need to recover a particular resource has passed,
|
||||||
|
a function that has called
|
||||||
|
.I waserror
|
||||||
|
must
|
||||||
|
remove the corresponding label from the stack by calling
|
||||||
|
.IR poperror .
|
||||||
|
This
|
||||||
|
must
|
||||||
|
be done before returning from the function; otherwise, a subsequent call to
|
||||||
|
.I error
|
||||||
|
will return to an obsolete activation record, with unpredictable but unpleasant consequences.
|
||||||
|
.PP
|
||||||
|
.I Error
|
||||||
|
copies the given error message, which is limited to
|
||||||
|
.B ERRMAX
|
||||||
|
bytes, into the
|
||||||
|
.B Proc.errstr
|
||||||
|
of the current process,
|
||||||
|
enables interrupts by calling
|
||||||
|
.I spllo
|
||||||
|
.RI ( native
|
||||||
|
only),
|
||||||
|
and finally calls
|
||||||
|
.I nexterror
|
||||||
|
to start invoking the recovery procedures currently stacked by
|
||||||
|
.IR waserror .
|
||||||
|
The file
|
||||||
|
.B /sys/src/9/port/error.h
|
||||||
|
offers a wide selection of predefined error messages, suitable for almost any occasion.
|
||||||
|
The message set by the most recent call to
|
||||||
|
.I error
|
||||||
|
can be obtained within the kernel by examining
|
||||||
|
.B up->error
|
||||||
|
and in an application, by using the
|
||||||
|
.L %r
|
||||||
|
directive of
|
||||||
|
.IR print (2).
|
||||||
|
.PP
|
||||||
|
A complex function can have nested error handlers.
|
||||||
|
A
|
||||||
|
.I waserror
|
||||||
|
block will follow the acquisition of a resource, releasing it
|
||||||
|
on error before calling
|
||||||
|
.I nexterror,
|
||||||
|
and a
|
||||||
|
.I poperror
|
||||||
|
will precede its release in the normal case.
|
||||||
|
For example:
|
||||||
|
.IP
|
||||||
|
.EX
|
||||||
|
.DT
|
||||||
|
void
|
||||||
|
outer(Thing *t)
|
||||||
|
{
|
||||||
|
qlock(t);
|
||||||
|
if(waserror()){ /* A */
|
||||||
|
qunlock(t);
|
||||||
|
nexterror();
|
||||||
|
}
|
||||||
|
m = mallocz(READSTR, 0);
|
||||||
|
if(m == nil)
|
||||||
|
error(Enomem); /* returns to A */
|
||||||
|
if(waserror()){ /* B */
|
||||||
|
free(m);
|
||||||
|
nexterror(); /* invokes A */
|
||||||
|
}
|
||||||
|
inner(t);
|
||||||
|
poperror(); /* pops B */
|
||||||
|
free(m);
|
||||||
|
poperror(); /* pops A */
|
||||||
|
qunlock(t);
|
||||||
|
}
|
||||||
|
.sp 1v
|
||||||
|
void
|
||||||
|
inner(Thing *t)
|
||||||
|
{
|
||||||
|
if(t->bad)
|
||||||
|
error(Egreg); /* returns to B */
|
||||||
|
t->valid++;
|
||||||
|
}
|
||||||
|
.EE
|
||||||
|
.SH SOURCE
|
||||||
|
.B /sys/src/9/port/proc.c
|
||||||
|
.SH CAVEATS
|
||||||
|
The description above has many instances of
|
||||||
|
.IR should ,
|
||||||
|
.IR will ,
|
||||||
|
.I must
|
||||||
|
and
|
||||||
|
.IR "must not" .
|
||||||
|
.SH SEE ALSO
|
||||||
|
.IR panic (9),
|
||||||
|
.IR kproc (9),
|
||||||
|
.IR splhi (9)
|
||||||
46
sys/man/9/eve
Normal file
46
sys/man/9/eve
Normal file
|
|
@ -0,0 +1,46 @@
|
||||||
|
.TH EVE 9
|
||||||
|
.SH NAME
|
||||||
|
eve, iseve \- privileged user
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.ta \w'\fLchar* 'u
|
||||||
|
.B
|
||||||
|
char *eve;
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
int iseve(void)
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.I Eve
|
||||||
|
is a null-terminated string containing the name of the owner of
|
||||||
|
the Plan 9 system (sometimes called the `host owner',
|
||||||
|
see
|
||||||
|
.IR cons (3)).
|
||||||
|
The identity is set on a terminal to the name of the user who logs in.
|
||||||
|
It is set on a CPU server to the
|
||||||
|
.I authid
|
||||||
|
obtained either from NVRAM or by a console prompt.
|
||||||
|
The initial process created by system initialisation is given the
|
||||||
|
.I eve
|
||||||
|
identity.
|
||||||
|
.PP
|
||||||
|
.I Iseve
|
||||||
|
returns true if the current user is
|
||||||
|
.IR eve .
|
||||||
|
Several drivers use
|
||||||
|
.I iseve
|
||||||
|
to check the caller's identity
|
||||||
|
before granting permission to perform certain actions.
|
||||||
|
For example, the console driver allows only the user
|
||||||
|
.I eve
|
||||||
|
to write a new identity into the
|
||||||
|
.B /dev/user
|
||||||
|
file.
|
||||||
|
The privileges are strictly local and do not extend into the network
|
||||||
|
(in particular, to file servers—even ones running on the local machine).
|
||||||
|
.SH SOURCE
|
||||||
|
.B /sys/src/9/port/auth.c
|
||||||
|
.SH SEE ALSO
|
||||||
|
.IR auth (2),
|
||||||
|
.IR cap (3),
|
||||||
|
.IR cons (3),
|
||||||
|
.IR authsrv (6),
|
||||||
|
.IR auth (8)
|
||||||
106
sys/man/9/intrenable
Normal file
106
sys/man/9/intrenable
Normal file
|
|
@ -0,0 +1,106 @@
|
||||||
|
.TH INTRENABLE 9
|
||||||
|
.SH NAME
|
||||||
|
intrenable, intrdisable \- enable (disable) an interrupt handler
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.ta \w'\fLvoid* 'u
|
||||||
|
.B
|
||||||
|
void intrenable(int v, void (*f)(Ureg*, void*), void* a, int tbdf, char *name)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void intrdisable(int v, void (*f)(Ureg*, void*), void* a, int tbdf, char *name)
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.I Intrenable
|
||||||
|
registers
|
||||||
|
.I f
|
||||||
|
to be called by the kernel's interrupt controller driver each time
|
||||||
|
an interrupt denoted by
|
||||||
|
.I v
|
||||||
|
occurs, and unmasks the corresponding interrupt in the interrupt controller.
|
||||||
|
The encoding of
|
||||||
|
.I v
|
||||||
|
is platform-dependent; it is often an interrupt vector number, but
|
||||||
|
can be more complex.
|
||||||
|
.I Tbdf
|
||||||
|
is a platform-dependent value that might further qualify
|
||||||
|
.IR v .
|
||||||
|
It might for instance
|
||||||
|
denote the type of bus, bus instance, device number and function
|
||||||
|
(following the PCI device indexing scheme), hence its name,
|
||||||
|
but can have platform-dependent meaning.
|
||||||
|
.I Name
|
||||||
|
is a string that should uniquely identify the corresponding device (eg, \f5"uart0"\fP);
|
||||||
|
again it is usually platform-dependent.
|
||||||
|
.I Intrenable
|
||||||
|
supports sharing of interrupt levels when the hardware does.
|
||||||
|
.PP
|
||||||
|
Almost invariably
|
||||||
|
.I f
|
||||||
|
is a function defined in a device driver to carry out the device-specific work associated with a given interrupt.
|
||||||
|
The pointer
|
||||||
|
.I a
|
||||||
|
is passed to
|
||||||
|
.IR f ;
|
||||||
|
typically it points to the driver's data for a given device or controller.
|
||||||
|
It also passes
|
||||||
|
.I f
|
||||||
|
a
|
||||||
|
.B Ureg*
|
||||||
|
value that
|
||||||
|
contains the registers saved by the interrupt handler (the
|
||||||
|
contents are platform specific;
|
||||||
|
see the platform's include file
|
||||||
|
.BR "ureg.h" ).
|
||||||
|
.PP
|
||||||
|
.I F
|
||||||
|
is invoked by underlying code in the kernel that is invoked directly from the hardware vectors.
|
||||||
|
It is therefore not running in any process (see
|
||||||
|
.IR kproc (9);
|
||||||
|
indeed, on many platforms
|
||||||
|
the current process pointer
|
||||||
|
.RB ( up )
|
||||||
|
will be nil.
|
||||||
|
There are many restrictions on kernel functions running outside a process, but a fundamental one is that
|
||||||
|
they must not
|
||||||
|
.IR sleep (9),
|
||||||
|
although they often call
|
||||||
|
.B wakeup
|
||||||
|
to signal the occurrence of an event associated with the interrupt.
|
||||||
|
.IR Qio (9)
|
||||||
|
and other manual pages note which functions are safe for
|
||||||
|
.I f
|
||||||
|
to call.
|
||||||
|
.PP
|
||||||
|
The interrupt controller driver does whatever is
|
||||||
|
required to acknowledge or dismiss the interrupt signal in the interrupt controller,
|
||||||
|
before calling
|
||||||
|
.IR f ,
|
||||||
|
for edge-triggered interrupts,
|
||||||
|
and after calling
|
||||||
|
.I f
|
||||||
|
for level-triggered ones.
|
||||||
|
.I F
|
||||||
|
is responsible for dealing with the cause of the interrupt in the device, including any
|
||||||
|
acknowledgement required in the device, before it returns.
|
||||||
|
.PP
|
||||||
|
.I Intrdisable
|
||||||
|
removes any registration previously made by
|
||||||
|
.I intrenable
|
||||||
|
with matching parameters, and if no other
|
||||||
|
interrupt is active on
|
||||||
|
.IR v ,
|
||||||
|
it masks the interrupt in the controller.
|
||||||
|
Device drivers that are not dynamically configured tend to call
|
||||||
|
.I intrenable
|
||||||
|
during reset or initialisation (see
|
||||||
|
.IR dev (9)),
|
||||||
|
but can call it at any appropriate time, and
|
||||||
|
instead of calling
|
||||||
|
.I intrdisable
|
||||||
|
they can simply enable or disable interrupts in the device as required.
|
||||||
|
.SH SOURCE
|
||||||
|
.B /sys/src/9/*/trap.c
|
||||||
|
.SH SEE ALSO
|
||||||
|
.IR malloc (9),
|
||||||
|
.IR qio (9),
|
||||||
|
.IR sleep (9),
|
||||||
|
.IR splhi (9)
|
||||||
134
sys/man/9/kproc
Normal file
134
sys/man/9/kproc
Normal file
|
|
@ -0,0 +1,134 @@
|
||||||
|
.TH KPROC 9
|
||||||
|
.SH NAME
|
||||||
|
kproc, pexit, postnote \- kernel process creation, termination and interruption
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.ta \w'\fLvoid 'u
|
||||||
|
.B
|
||||||
|
void kproc(char *name, void (*func)(void*), void *arg)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void pexit(char *note, int freemem)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
int postnote(Proc *p, int dolock, char *n, int flag)
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.I Kproc
|
||||||
|
creates a new kernel process
|
||||||
|
to run the function
|
||||||
|
.IR func ,
|
||||||
|
which is invoked as
|
||||||
|
.BR "(*func)(arg)" .
|
||||||
|
The string
|
||||||
|
.I name
|
||||||
|
is copied into the
|
||||||
|
.B text
|
||||||
|
field of the
|
||||||
|
.B Proc
|
||||||
|
structure of the new process; this value is the name of the kproc in
|
||||||
|
the output of
|
||||||
|
.IR ps (1).
|
||||||
|
The process is made runnable; it
|
||||||
|
will run when selected by the scheduler
|
||||||
|
.IR sched (9).
|
||||||
|
The process is created with base and current priorities set to
|
||||||
|
.BR PriKproc .
|
||||||
|
It shares the kernel process group and thus name space.
|
||||||
|
.PP
|
||||||
|
A kernel process terminates only when it calls
|
||||||
|
.IR pexit ,
|
||||||
|
thereby terminating itself.
|
||||||
|
There is no mechanism for one process to force the termination of another,
|
||||||
|
although it can send a software interrupt using
|
||||||
|
.IR postnote .
|
||||||
|
.I Note
|
||||||
|
is a null string on normal termination, or
|
||||||
|
the cause of
|
||||||
|
If
|
||||||
|
.I freemem
|
||||||
|
is non-zero,
|
||||||
|
any memory allocated by the process is discarded;
|
||||||
|
it should normally be non-zero for any process created
|
||||||
|
by
|
||||||
|
.IR kproc .
|
||||||
|
Use the following to terminate a kernel process normally:
|
||||||
|
.IP
|
||||||
|
.EX
|
||||||
|
pexit("", 1);
|
||||||
|
.EE
|
||||||
|
.PP
|
||||||
|
to terminate a kernel process normally.
|
||||||
|
.PP
|
||||||
|
.I Postnote
|
||||||
|
sends a software interrupt to process
|
||||||
|
.IR p ,
|
||||||
|
causing it, if necessary, to wake from
|
||||||
|
.IR sleep (9)
|
||||||
|
or break out of a
|
||||||
|
.IR rendezvous (2)
|
||||||
|
or an
|
||||||
|
.IR eqlock(9),
|
||||||
|
with an
|
||||||
|
.IR error (9)
|
||||||
|
`interrupted'.
|
||||||
|
Up to
|
||||||
|
.B NNOTE
|
||||||
|
notes can be pending at once (currently 5);
|
||||||
|
if more than that arrive, the process is forced
|
||||||
|
out of
|
||||||
|
.IR sleep ,
|
||||||
|
.I rendezvous
|
||||||
|
and
|
||||||
|
.IR eqlock ,
|
||||||
|
but the message itself is discarded.
|
||||||
|
.I Postnote
|
||||||
|
returns non-zero iff the note has been
|
||||||
|
delivered successfully.
|
||||||
|
If
|
||||||
|
.I dolock
|
||||||
|
is non-zero,
|
||||||
|
.I postnote
|
||||||
|
synchronises delivery of the note with the debugger
|
||||||
|
and other operations of
|
||||||
|
.IR proc (3).
|
||||||
|
.I Flag
|
||||||
|
is zero, or one of the following
|
||||||
|
.TP
|
||||||
|
.B NDebug
|
||||||
|
Print the note message on the user's standard error.
|
||||||
|
Furthermore, suspend the process in a
|
||||||
|
.B Broken
|
||||||
|
state, preserving its memory, for later debugging.
|
||||||
|
.TP
|
||||||
|
.B NExit
|
||||||
|
Deliver the note quietly.
|
||||||
|
.TP
|
||||||
|
.B NUser
|
||||||
|
The note comes from another process, not the system.
|
||||||
|
.PP
|
||||||
|
The kernel uses
|
||||||
|
.I postnote
|
||||||
|
to signal processes that commit grave faults,
|
||||||
|
and to implement the note and kill functions of
|
||||||
|
.IR proc (3).
|
||||||
|
A device driver should use
|
||||||
|
.I postnote
|
||||||
|
only to tell a service process,
|
||||||
|
previously started by the driver using
|
||||||
|
.I kproc ,
|
||||||
|
that it should stop;
|
||||||
|
the note will cause that process to raise an
|
||||||
|
.IR error (9).
|
||||||
|
For example, a process started to read packets from a network device could
|
||||||
|
be stopped as follows when the interface is unbound:
|
||||||
|
.IP
|
||||||
|
.EX
|
||||||
|
postnote(readp, 1, "unbind", 0);
|
||||||
|
.EE
|
||||||
|
.PP
|
||||||
|
where
|
||||||
|
.I readp
|
||||||
|
points to the appropriate
|
||||||
|
.BR Proc .
|
||||||
|
The text of the message is typically irrelevant.
|
||||||
|
.SH SOURCE
|
||||||
|
.B /sys/src/9/port/proc.c
|
||||||
187
sys/man/9/malloc
Normal file
187
sys/man/9/malloc
Normal file
|
|
@ -0,0 +1,187 @@
|
||||||
|
.TH MALLOC 9
|
||||||
|
.SH NAME
|
||||||
|
malloc, mallocz, smalloc, realloc, free, msize, secalloc, secfree, setmalloctag, setrealloctag, getmalloctag, getrealloctag \- kernel memory allocator
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.ta \w'\fLvoid* 'u
|
||||||
|
.B
|
||||||
|
void* malloc(ulong size)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void* mallocalign(ulong size, ulong align, long offset, ulong span)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void* mallocz(ulong size, int clr)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void* smalloc(ulong size)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void* realloc(void *p, ulong size)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void free(void *ptr)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
ulong msize(void *ptr)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void* secalloc(ulong size)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void secfree(void *ptr)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void setmalloctag(void *ptr, ulong tag)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
ulong getmalloctag(void *ptr)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void setrealloctag(void *ptr, ulong tag)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
ulong getrealloctag(void *ptr)
|
||||||
|
.PP
|
||||||
|
.SH DESCRIPTION
|
||||||
|
These are kernel versions of the functions in
|
||||||
|
.IR malloc (2).
|
||||||
|
They allocate memory from the
|
||||||
|
.B mainmem
|
||||||
|
memory pool,
|
||||||
|
which is managed by
|
||||||
|
the allocator
|
||||||
|
.IR pool (2),
|
||||||
|
which in turn replenishes the pool as required by calling
|
||||||
|
.IR xalloc (9).
|
||||||
|
All but
|
||||||
|
.I smalloc
|
||||||
|
(which calls
|
||||||
|
.IR sleep (9))
|
||||||
|
may safely be called by interrupt handlers.
|
||||||
|
.PP
|
||||||
|
.I Malloc
|
||||||
|
returns a pointer to a block of at least
|
||||||
|
.I size
|
||||||
|
bytes, initialised to zero.
|
||||||
|
The block is suitably aligned for storage of any type of object.
|
||||||
|
The call
|
||||||
|
.B malloc(0)
|
||||||
|
returns a valid pointer rather than null.
|
||||||
|
.I Mallocz
|
||||||
|
is similar, but only clears the memory if
|
||||||
|
.I clr
|
||||||
|
is non-zero.
|
||||||
|
.PP
|
||||||
|
.I Smalloc
|
||||||
|
returns a pointer to a block of
|
||||||
|
.I size
|
||||||
|
bytes, initialised to zero.
|
||||||
|
If the memory is not immediately available,
|
||||||
|
.I smalloc
|
||||||
|
retries every 100 milliseconds until the memory is acquired.
|
||||||
|
.PP
|
||||||
|
.I Mallocalign
|
||||||
|
allocates a block of at least
|
||||||
|
.I n
|
||||||
|
bytes of memory respecting alignment contraints.
|
||||||
|
If
|
||||||
|
.I align
|
||||||
|
is non-zero,
|
||||||
|
the returned pointer is aligned to be equal to
|
||||||
|
.I offset
|
||||||
|
modulo
|
||||||
|
.IR align .
|
||||||
|
If
|
||||||
|
.I span
|
||||||
|
is non-zero,
|
||||||
|
the
|
||||||
|
.I n
|
||||||
|
byte block allocated will not span a
|
||||||
|
.IR span -byte
|
||||||
|
boundary.
|
||||||
|
.PP
|
||||||
|
.I Realloc
|
||||||
|
changes the size of the block pointed to by
|
||||||
|
.I p
|
||||||
|
to
|
||||||
|
.I size
|
||||||
|
bytes,
|
||||||
|
if possible without moving the data,
|
||||||
|
and returns a pointer to the block.
|
||||||
|
The contents are unchanged up to the lesser of old and new sizes,
|
||||||
|
and any new space allocated is initialised to zero.
|
||||||
|
.I Realloc
|
||||||
|
takes on special meanings when one or both arguments are zero:
|
||||||
|
.TP
|
||||||
|
.B "realloc(0,\ size)
|
||||||
|
means
|
||||||
|
.LR malloc(size) ;
|
||||||
|
returns a pointer to the newly-allocated memory
|
||||||
|
.TP
|
||||||
|
.B "realloc(ptr,\ 0)
|
||||||
|
means
|
||||||
|
.LR free(ptr) ;
|
||||||
|
returns null
|
||||||
|
.TP
|
||||||
|
.B "realloc(0,\ 0)
|
||||||
|
no-op; returns null
|
||||||
|
.PD
|
||||||
|
.PP
|
||||||
|
The argument to
|
||||||
|
.I free
|
||||||
|
is a pointer to a block of memory allocated by one of the routines above, which
|
||||||
|
is returned to the allocation pool, or a null pointer, which is ignored.
|
||||||
|
.PP
|
||||||
|
When a block is allocated, sometimes there is some extra unused space at the end.
|
||||||
|
.I Msize
|
||||||
|
grows the block to encompass this unused space and returns the new number
|
||||||
|
of bytes that may be used.
|
||||||
|
.PP
|
||||||
|
.I Secalloc
|
||||||
|
and
|
||||||
|
.I secfree
|
||||||
|
are security-aware functions that use a pool flagged by
|
||||||
|
.B POOL_ANTAGONISM
|
||||||
|
(see
|
||||||
|
.IR pool (2)),
|
||||||
|
which fills every allocated block with garbage before and after its
|
||||||
|
use, to prevent leakage.
|
||||||
|
.PP
|
||||||
|
The memory allocator maintains two word-sized fields
|
||||||
|
associated with each block, the ``malloc tag'' and the ``realloc tag''.
|
||||||
|
By convention, the malloc tag is the PC that allocated the block,
|
||||||
|
and the realloc tag the PC that last reallocated the block.
|
||||||
|
These may be set or examined with
|
||||||
|
.IR setmalloctag ,
|
||||||
|
.IR getmalloctag ,
|
||||||
|
.IR setrealloctag ,
|
||||||
|
and
|
||||||
|
.IR getrealloctag .
|
||||||
|
When allocating blocks directly with
|
||||||
|
.I malloc
|
||||||
|
and
|
||||||
|
.IR realloc ,
|
||||||
|
these tags will be set properly.
|
||||||
|
If a custom allocator wrapper is used,
|
||||||
|
the allocator wrapper can set the tags
|
||||||
|
itself (usually by passing the result of
|
||||||
|
.IR getcallerpc (2)
|
||||||
|
to
|
||||||
|
.IR setmalloctag )
|
||||||
|
to provide more useful information about
|
||||||
|
the source of allocation.
|
||||||
|
.SH SOURCE
|
||||||
|
.B /sys/src/9/port/alloc.c
|
||||||
|
.SH DIAGNOSTICS
|
||||||
|
All functions except
|
||||||
|
.I smalloc
|
||||||
|
return a null pointer if space is unavailable.
|
||||||
|
If the allocated blocks have no malloc or realloc tags,
|
||||||
|
.I getmalloctag
|
||||||
|
and
|
||||||
|
.I getrealloctag
|
||||||
|
return
|
||||||
|
.BR ~0 .
|
||||||
|
.SH SEE ALSO
|
||||||
|
.IR pool (2),
|
||||||
|
.IR xalloc (9)
|
||||||
25
sys/man/9/panic
Normal file
25
sys/man/9/panic
Normal file
|
|
@ -0,0 +1,25 @@
|
||||||
|
.TH PANIC 9
|
||||||
|
.SH NAME
|
||||||
|
panic \- abandon hope, all ye who enter here
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.ta \w'\fLvoid 'u
|
||||||
|
.B
|
||||||
|
void panic(char *fmt, ...)
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.I Panic
|
||||||
|
writes a message to the console and
|
||||||
|
causes the system to give up the host.
|
||||||
|
It enables interrupts, dumps the kernel stack,
|
||||||
|
and halts the current processor;
|
||||||
|
if more than one, others will gradually come to a halt.
|
||||||
|
Depending on configuration settings, the platform-dependent
|
||||||
|
.I exit
|
||||||
|
might reboot the system.
|
||||||
|
The format
|
||||||
|
.I fmt
|
||||||
|
and associated arguments are the same as those for
|
||||||
|
.IR print (9).
|
||||||
|
.I Panic
|
||||||
|
adds a prefix
|
||||||
|
.L "panic: "
|
||||||
|
and a trailing newline.
|
||||||
138
sys/man/9/qlock
Normal file
138
sys/man/9/qlock
Normal file
|
|
@ -0,0 +1,138 @@
|
||||||
|
.TH QLOCK 9
|
||||||
|
.SH NAME
|
||||||
|
qlock, qunlock, canqlock, rlock, runlock, wlock, wunlock \- serial synchronisation
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.de PB
|
||||||
|
.PP
|
||||||
|
.ft L
|
||||||
|
.nf
|
||||||
|
..
|
||||||
|
.PB
|
||||||
|
typedef struct
|
||||||
|
{
|
||||||
|
Lock use; /* to access Qlock structure */
|
||||||
|
Proc *head; /* next process waiting for object */
|
||||||
|
Proc *tail; /* last process waiting for object */
|
||||||
|
int locked; /* flag */
|
||||||
|
} QLock;
|
||||||
|
.PB
|
||||||
|
typedef struct
|
||||||
|
{
|
||||||
|
Lock use;
|
||||||
|
Proc *head; /* list of waiting processes */
|
||||||
|
Proc *tail;
|
||||||
|
uintptr wpc; /* pc of writer */
|
||||||
|
Proc *wproc; /* writing proc */
|
||||||
|
int readers; /* number of readers */
|
||||||
|
int writer; /* number of writers */
|
||||||
|
} RWlock;
|
||||||
|
.ta \w'\fLvoid 'u
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void eqlock(QLock *l)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void qlock(QLock *l)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void qunlock(QLock *l)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
int canqlock(QLock *l)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void rlock(RWlock *l)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void runlock(RWlock *l)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
int canrlock(RWlock *l)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void wlock(RWlock *l)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void wunlock(RWlock *l)
|
||||||
|
.SH DESCRIPTION
|
||||||
|
The primitive locking functions described in
|
||||||
|
.IR lock (9)
|
||||||
|
guarantee mutual exclusion, but they implement spin locks,
|
||||||
|
and should not be used if the process might
|
||||||
|
.IR sleep (9)
|
||||||
|
within a critical section.
|
||||||
|
The following functions serialise access to a resource by forming an orderly
|
||||||
|
queue of processes.
|
||||||
|
.PP
|
||||||
|
Each resource to be controlled is given an associated
|
||||||
|
.B QLock
|
||||||
|
structure; it is usually most straightforward to put the
|
||||||
|
.B QLock
|
||||||
|
in the structure that represents the resource.
|
||||||
|
It must be initialised to zero before use
|
||||||
|
(as guaranteed for global variables and for structures allocated by
|
||||||
|
.IR malloc ).
|
||||||
|
.PP
|
||||||
|
On return from
|
||||||
|
.IR qlock ,
|
||||||
|
the process has acquired the lock
|
||||||
|
.IR l ,
|
||||||
|
and can assume exclusive access to the associated resource.
|
||||||
|
If the lock is not immediately available, the requesting process is placed on a
|
||||||
|
FIFO queue of processes that have requested the lock.
|
||||||
|
Processes on this list are blocked in the
|
||||||
|
.L Queueing
|
||||||
|
state.
|
||||||
|
.PP
|
||||||
|
.I Eqlock
|
||||||
|
is an interruptible form of
|
||||||
|
.IR qlock.
|
||||||
|
.PP
|
||||||
|
.I Qunlock
|
||||||
|
unlocks
|
||||||
|
.I l
|
||||||
|
and schedules the first process queued for it (if any).
|
||||||
|
.PP
|
||||||
|
.I Canqlock
|
||||||
|
is a non-blocking form of
|
||||||
|
.IR qlock .
|
||||||
|
It tries to obtain the lock
|
||||||
|
.I l
|
||||||
|
and returns true if successful, and 0 otherwise;
|
||||||
|
it always returns immediately.
|
||||||
|
.PP
|
||||||
|
.B RWlock
|
||||||
|
is a form of lock for resources that have distinct readers and writers.
|
||||||
|
It allows concurrent readers but gives each writer exclusive access.
|
||||||
|
A caller announces its read or write intentions by choice of lock (and unlock) function;
|
||||||
|
the system assumes the caller will not modify a structure accessed under read lock.
|
||||||
|
.PP
|
||||||
|
.I Rlock
|
||||||
|
acquires
|
||||||
|
.I l
|
||||||
|
for reading.
|
||||||
|
The holder can read but agrees not to modify the resource.
|
||||||
|
There may be several concurrent readers.
|
||||||
|
.I Canrlock
|
||||||
|
is non-blocking: it returns non-zero if it successfully acquired the lock immediately,
|
||||||
|
and 0 if the resource was unavailable.
|
||||||
|
.PP
|
||||||
|
.I Runlock
|
||||||
|
returns a read lock;
|
||||||
|
the last reader out enables the first writer waiting (if any).
|
||||||
|
.PP
|
||||||
|
.I Wlock
|
||||||
|
acquires a write lock.
|
||||||
|
The holder of such a lock may assume exclusive access to the resource,
|
||||||
|
and is allowed to modify it.
|
||||||
|
.PP
|
||||||
|
.I Wunlock
|
||||||
|
returns a write lock.
|
||||||
|
The next pending process, whether reader or writer, is scheduled.
|
||||||
|
.SH SOURCE
|
||||||
|
.B /sys/src/9/port/qlock.c
|
||||||
|
.br
|
||||||
|
.SH SEE ALSO
|
||||||
|
.IR lock (9),
|
||||||
|
.IR malloc (9),
|
||||||
|
.IR splhi (9)
|
||||||
125
sys/man/9/sleep
Normal file
125
sys/man/9/sleep
Normal file
|
|
@ -0,0 +1,125 @@
|
||||||
|
.TH SLEEP 9
|
||||||
|
.SH NAME
|
||||||
|
sleep, wakeup, tsleep, return0 \- process synchronisation
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.ta \w'\fLvoid 'u
|
||||||
|
.B
|
||||||
|
void sleep(Rendez *r, int (*f)(void*), void *arg)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void wakeup(Rendez *r)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void tsleep(Rendez *r, int (*f)(void*), void *arg, ulong ms)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
int return0(void *arg)
|
||||||
|
.PP
|
||||||
|
.SH DESCRIPTION
|
||||||
|
A process running in the kernel can use these functions to
|
||||||
|
synchronise with an interrupt handler or another kernel process.
|
||||||
|
In particular, they are used by device drivers to wait for an event to be signalled on
|
||||||
|
receipt of an interrupt.
|
||||||
|
(In practice, they are most often used indirectly, through
|
||||||
|
.IR qio (9)
|
||||||
|
for instance.)
|
||||||
|
.PP
|
||||||
|
The caller of
|
||||||
|
.I sleep
|
||||||
|
and a caller of
|
||||||
|
.I wakeup
|
||||||
|
share a
|
||||||
|
.B Rendez
|
||||||
|
structure, to provide a rendezvous point between them
|
||||||
|
to synchronise on an event.
|
||||||
|
.I Sleep
|
||||||
|
uses a condition function
|
||||||
|
.I f
|
||||||
|
that returns true if the event has occurred.
|
||||||
|
.PP
|
||||||
|
.I Sleep
|
||||||
|
evaluates
|
||||||
|
.IB f ( arg ).
|
||||||
|
If true, the event has happened and
|
||||||
|
.I sleep
|
||||||
|
returns immediately.
|
||||||
|
Otherwise,
|
||||||
|
.I sleep
|
||||||
|
blocks on the event variable
|
||||||
|
.IR r ,
|
||||||
|
awaiting
|
||||||
|
.IR wakeup .
|
||||||
|
.PP
|
||||||
|
.I Wakeup
|
||||||
|
is called by either a process or an interrupt handler to wake any process
|
||||||
|
sleeping at
|
||||||
|
.IR r ,
|
||||||
|
signifying that the corresponding condition is true (the event has occurred).
|
||||||
|
It has no effect if there is no sleeping process.
|
||||||
|
.PP
|
||||||
|
.I Tsleep
|
||||||
|
is similar to
|
||||||
|
.IR sleep ,
|
||||||
|
except that if the condition
|
||||||
|
.IB f ( arg )
|
||||||
|
is false and the caller does sleep,
|
||||||
|
and nothing else wakes it within
|
||||||
|
.I ms
|
||||||
|
millliseconds,
|
||||||
|
the system will wake it.
|
||||||
|
.IR Tsleep 's
|
||||||
|
caller must check its environment to decide whether timeout or the event
|
||||||
|
occurred.
|
||||||
|
The timing provided by
|
||||||
|
.I tsleep
|
||||||
|
is imprecise, but adequate in practice for the normal use of protecting against
|
||||||
|
lost interrupts and otherwise unresponsive devices or software.
|
||||||
|
.PP
|
||||||
|
.I Return0
|
||||||
|
ignores its arguments and returns zero. It is commonly used as
|
||||||
|
the predicate
|
||||||
|
.I f
|
||||||
|
in a call to
|
||||||
|
.I tsleep
|
||||||
|
to obtain a time delay, using the
|
||||||
|
.B Rendez
|
||||||
|
variable
|
||||||
|
.B sleep
|
||||||
|
in the
|
||||||
|
.B Proc
|
||||||
|
structure, for example:
|
||||||
|
.IP
|
||||||
|
.B tsleep(&up->sleep, return0, nil, 10);
|
||||||
|
.PP
|
||||||
|
Both
|
||||||
|
.I sleep
|
||||||
|
and
|
||||||
|
.I tsleep
|
||||||
|
can be interrupted by
|
||||||
|
.IR swiproc
|
||||||
|
(see
|
||||||
|
.IR kproc (9)),
|
||||||
|
causing a non-local goto through a call to
|
||||||
|
.IR error (9).
|
||||||
|
.SH SOURCE
|
||||||
|
.B /sys/src/9/port/proc.c
|
||||||
|
.br
|
||||||
|
.B /sys/src/9/port/sysproc.c
|
||||||
|
.SH DIAGNOSTICS
|
||||||
|
There can be at most one process waiting on a
|
||||||
|
.BR Rendez ,
|
||||||
|
and if two processes collide, the system will
|
||||||
|
.IR panic (9)
|
||||||
|
.RB (`` "double sleep" '').
|
||||||
|
Access to a
|
||||||
|
.B Rendez
|
||||||
|
must therefore be serialised by some other mechanism, usually
|
||||||
|
.IR qlock (9).
|
||||||
|
.SH SEE ALSO
|
||||||
|
.IR lock (9),
|
||||||
|
.IR qlock (9),
|
||||||
|
.IR delay (9)
|
||||||
|
.br
|
||||||
|
``Process Sleep and Wakeup on a Shared-memory Multiprocessor'',
|
||||||
|
in
|
||||||
|
.I "Plan 9 Programmer's Manual: Volume 2".
|
||||||
56
sys/man/9/splhi
Normal file
56
sys/man/9/splhi
Normal file
|
|
@ -0,0 +1,56 @@
|
||||||
|
.TH SPLHI 9
|
||||||
|
.SH NAME
|
||||||
|
splhi, spllo, splx, islo \- enable and disable interrupts
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.ta \w'\fLvoid 'u
|
||||||
|
.B
|
||||||
|
int spllo(void)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
int splhi(void)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void splx(int x)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
int islo(void)
|
||||||
|
.SH DESCRIPTION
|
||||||
|
These primitives enable and disable maskable interrupts on the current
|
||||||
|
processor.
|
||||||
|
Generally, device drivers should use
|
||||||
|
.I ilock
|
||||||
|
(see
|
||||||
|
.IR lock (9)),
|
||||||
|
.IR sleep (9),
|
||||||
|
or the functions in
|
||||||
|
.IR qio (9)
|
||||||
|
to control interaction between processes and interrupt handlers.
|
||||||
|
Those routines (but not these) provide correct synchronisation on multiprocessors.
|
||||||
|
.PP
|
||||||
|
.I Spllo
|
||||||
|
enables interrupts and returns a flag representing the previous interrupt enable state.
|
||||||
|
It must not normally be called from interrupt level.
|
||||||
|
.PP
|
||||||
|
.I Splhi
|
||||||
|
disables all maskable interrupts and returns the previous interrupt enable state.
|
||||||
|
The period during which interrupts are disabled had best be short,
|
||||||
|
or real-time applications will suffer.
|
||||||
|
.PP
|
||||||
|
.I Splx
|
||||||
|
restores the interrupt enable state to
|
||||||
|
.IR x ,
|
||||||
|
which must be a value returned
|
||||||
|
by a previous call to
|
||||||
|
.I splhi
|
||||||
|
or
|
||||||
|
.IR spllo .
|
||||||
|
.PP
|
||||||
|
.I Islo
|
||||||
|
returns true (non-zero) if interrupts are currently enabled, and 0 otherwise.
|
||||||
|
.SH SOURCE
|
||||||
|
.B /sys/src/9/*/l.s
|
||||||
|
.SH SEE ALSO
|
||||||
|
.IR lock (9),
|
||||||
|
.IR qio (9),
|
||||||
|
.IR sleep (9),
|
||||||
|
.IR intrenable (9)
|
||||||
81
sys/man/9/xalloc
Normal file
81
sys/man/9/xalloc
Normal file
|
|
@ -0,0 +1,81 @@
|
||||||
|
.TH XALLOC 9
|
||||||
|
.SH NAME
|
||||||
|
xalloc, xallocz, xspanalloc, xfree, xsummary \- basic memory management
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.ta \w'\fLvoid* 'u
|
||||||
|
.B
|
||||||
|
void* xalloc(ulong size)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void* xallocz(ulong size, int clr)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void* xspanalloc(ulong size, int align, ulong span)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void xfree(void *p)
|
||||||
|
.PP
|
||||||
|
.B
|
||||||
|
void xsummary(void)
|
||||||
|
.SH DESCRIPTION
|
||||||
|
These are primitives used by higher-level memory allocators in the kernel,
|
||||||
|
such as
|
||||||
|
.IR malloc (9).
|
||||||
|
They are not intended for use directly by most kernel routines.
|
||||||
|
The main exceptions are routines that permanently allocate large structures,
|
||||||
|
or need the special alignment properties guaranteed by
|
||||||
|
.IR xspanalloc .
|
||||||
|
.PP
|
||||||
|
.I Xalloc
|
||||||
|
returns a pointer to a range of size bytes of memory. The memory will be zero filled and aligned on a 8 byte
|
||||||
|
.RB ( BY2V )
|
||||||
|
address. If the memory is not available,
|
||||||
|
.B xalloc
|
||||||
|
returns a null pointer.
|
||||||
|
.PP
|
||||||
|
.I Xmallocz
|
||||||
|
will clear the memory after allocation if
|
||||||
|
.I clr
|
||||||
|
is set to a value other than zero. Since it is used by
|
||||||
|
.IR xmalloc ,
|
||||||
|
the same diagnostics apply.
|
||||||
|
.PP
|
||||||
|
.I Xspanalloc
|
||||||
|
allocates memory given alignment and spanning constraints.
|
||||||
|
The block returned will contain
|
||||||
|
.I size
|
||||||
|
bytes, aligned on a boundary that is
|
||||||
|
.BI "0 mod" " align,"
|
||||||
|
in such a way that the memory in the block does not
|
||||||
|
span an address that is
|
||||||
|
.BI "0 mod" " span."
|
||||||
|
.I Xspanalloc
|
||||||
|
is intended for use
|
||||||
|
allocating hardware data structures (eg, page tables) or I/O buffers
|
||||||
|
that must satisfy specific alignment restrictions.
|
||||||
|
If
|
||||||
|
.I xspanalloc
|
||||||
|
cannot allocate memory to satisfy the given constraints, it will
|
||||||
|
.IR panic (9).
|
||||||
|
The technique it uses can sometimes cause memory to be wasted.
|
||||||
|
Consequently,
|
||||||
|
.I xspanalloc
|
||||||
|
should be used sparingly.
|
||||||
|
.PP
|
||||||
|
.I Xfree
|
||||||
|
frees the block of memory at
|
||||||
|
.IR p ,
|
||||||
|
which must be an address previously returned by
|
||||||
|
.I xalloc
|
||||||
|
(not
|
||||||
|
.IR xspanalloc ).
|
||||||
|
.PP
|
||||||
|
.I Xsummary
|
||||||
|
dumps memory allocation statistics to the console.
|
||||||
|
The output includes the total free space, the number of free holes,
|
||||||
|
and a summary of active holes.
|
||||||
|
Each line shows `address top size'.
|
||||||
|
.SH SOURCE
|
||||||
|
.B /sys/src/9/port/xalloc.c
|
||||||
|
.SH SEE ALSO
|
||||||
|
.IR malloc (9)
|
||||||
Loading…
Reference in a new issue