Re: [9front] man: new section 9

Re: [9front] man: new section 9

[rgl]

[-- Attachment #1: Type: text/plain, Size: 23 bytes --]

ok, another two pages.

[-- Attachment #2: Type: text/plain, Size: 1096 bytes --]

diff -r 159c7e7ca171 sys/man/9/delay
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/sys/man/9/delay	Sat Nov 16 13:13:43 2019 +0100
@@ -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)

Re: [9front] man: new section 9

[rgl]

[-- Attachment #1: Type: text/plain, Size: 59 bytes --]

hi.

last batch for today, i'll try to send more tomorrow.

[-- Attachment #2: Type: text/plain, Size: 1270 bytes --]

diff -r 159c7e7ca171 sys/man/9/eve
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/sys/man/9/eve	Sat Nov 16 14:21:43 2019 +0100
@@ -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)

[-- Attachment #3: Type: text/plain, Size: 4226 bytes --]

diff -r 159c7e7ca171 sys/man/9/error
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/sys/man/9/error	Sat Nov 16 17:02:22 2019 +0100
@@ -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)

[-- Attachment #4: Type: text/plain, Size: 1450 bytes --]

diff -r 159c7e7ca171 sys/man/9/splhi
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/sys/man/9/splhi	Sat Nov 16 17:32:52 2019 +0100
@@ -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)

[-- Attachment #5: Type: text/plain, Size: 3329 bytes --]

diff -r 159c7e7ca171 sys/man/9/intrenable
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/sys/man/9/intrenable	Sat Nov 16 18:14:08 2019 +0100
@@ -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)

Re: [9front] man: new section 9

[rgl]

[-- Attachment #1: Type: text/plain, Size: 23 bytes --]

ok, another two pages.

[-- Attachment #2: Type: text/plain, Size: 1096 bytes --]

diff -r 159c7e7ca171 sys/man/9/delay
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/sys/man/9/delay	Sat Nov 16 13:13:43 2019 +0100
@@ -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)

[-- Attachment #3: Type: text/plain, Size: 2952 bytes --]

diff -r 159c7e7ca171 sys/man/9/sleep
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/sys/man/9/sleep	Sat Nov 16 13:49:26 2019 +0100
@@ -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".