Re: New manpage: locking(9)

[Paul Goyette <paul%vps1.whooppee.com@localhost>]

Great to have this.

I've attached a diff file with some minor wording/grammar changes.

WRT to the table of "applicability", I'm not sure I like having it say

	mutex(9)        yes         depends       depends

Can we maybe specify the dependency?  Perhaps

	mutex(9)        yes         ???           spin-mutex only




On Thu, 18 Jun 2015, Kamil Rytarowski wrote:

> > I'm attaching a proposition of locking(9).
> New version attached.
>
> Changes:
> 1. I was told that kernel halves are not used in NetBSD.
> 2. ras(9) is for userland only, remove it from USAGE.
>
> There are additional things to be done in intro(9):
> 1. Remove reference to dropped lock(9).
> 2. Include reference to pserialize(9).

-------------------------------------------------------------------------
| Paul Goyette     | PGP Key fingerprint:     | E-mail addresses:       |
| (Retired)        | FA29 0E3B 35AF E8AE 6651 | paul at whooppee.com    |
| Kernel Developer | 0786 F758 55DE 53BA 7731 | pgoyette at netbsd.org  |
-------------------------------------------------------------------------

--- patch-locking.9.orig	2015-06-19 06:40:52.000000000 +0800
+++ patch-locking.9.paul	2015-06-19 06:58:50.000000000 +0800
@@ -49,7 +49,7 @@
 .It
 To control concurrent access to shared resources (critical sections).
 .It
-Spawn tasks from an interrupt in the thread context.
+From an interrupt, spawn tasks with thread context.
 .It
 Mask interrupts from threads.
 .It
@@ -65,20 +65,21 @@
 - here run processes (represented by
 .Dv struct proc )
 and light-weight processes (represented by
-.Dv struc lwp
+.Dv struct lwp
 and known as kernel threads).
-Code in this context can sleep, block resources and posses address-space.
+Code in this context can sleep, block resources and possess address-space.
 .It
 .Em Software interrupt context
-- it's limited thread context.
+- provides a thread context.
 Code in this context must be processed shortly.
-These interrupts don't possess any address space context.
+These interrupts don't possess their own address space context.
 Software interrupts are a way of deferring hardware interrupts to do more
 expensive processing at a lower interrupt priority.
 .It
 .Em Hard interrupt context
-- code must be processed as quickly as possible.
-It's forbidden for a code here to sleep or access long-awaited resources.
+- code must be processed as rapidly as possible.
+It's forbidden for code here to sleep or to wait for resources that
+may be unavailable for extended periods of time.
 .El
 .Pp
 The main differences between processes and kernel threads are:
@@ -86,7 +87,8 @@
 .It
 Single process can own multiple kernel threads (LWPs).
 .It
-Process possesses address space context to map userland address space.
+Process possesses address space context to map userland address space,
+while kernel threads share a single common address space.
 .It
 Processes are designed for userland executables and kernel threads for
 in-kernel tasks.
@@ -98,7 +100,8 @@
 The
 .Nx
 kernel is written to run across multiple unicore and multicore CPUs.
-The following lists lists alphabetically.
+The following list identifies the tools that are used to coordinate and
+control access to shared resources.
 .Ss Atomic memory operations
 The
 .Nm atomic_ops
@@ -162,7 +165,7 @@
 .Xr cpu_switchto 9 .
 If a process is found to have been preempted during a restartable sequence,
 then its execution is rolled-back to the start of the sequence by resetting its
-program counter saved in its process control block (PCB).
+program counter to the value saved in its process control block (PCB).
 .Pp
 See
 .Xr ras 9 .
@@ -272,8 +275,8 @@
 synchronization primitive (lockmgr) was inefficient and slow to execute.
 In
 .Nx 5.0
-there were introduced massive performance improvements on multicore hardware
-by Andrew Doran under a sponsorship of The NetBSD Foundation.
+massive performance improvements on multicore hardware were introduced
+by Andrew Doran under the sponsorship of The NetBSD Foundation.
 .Pp
 This file first appeared in
 .Nx 8.0