> 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).
.\" $NetBSD$ .\" .\" Copyright (c) 2015 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Kamil Rytarowski. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd June 17, 2015 .Dt LOCKING 9 .Os .Sh NAME .Nm locking .Nd introduction to the kernel synchronization and interrupt control .Sh DESCRIPTION The .Nx kernel provides several synchronization and interrupt control primitives. This manpage aims at giving an overview of these interfaces and their proper application. This document includes also basic kernel thread control primitives and rough overview of the .Nx kernel design. .Sh KERNEL OVERVIEW The aim of the kernel synchronization, kernel thread and interrupt control is: .Bl -bullet -offset indent .It To control concurrent access to shared resources (critical sections). .It Spawn tasks from an interrupt in the thread context. .It Mask interrupts from threads. .It Scale to multiple CPUs. .El .Pp There are three types of contexts in the .Nx kernel: .Bl -bullet -offset indent .It .Em Thread context - here run processes (represented by .Dv struct proc ) and light-weight processes (represented by .Dv struc lwp and known as kernel threads). Code in this context can sleep, block resources and posses address-space. .It .Em Software interrupt context - it's limited thread context. Code in this context must be processed shortly. These interrupts don't possess any 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. .El .Pp The main differences between processes and kernel threads are: .Bl -bullet -offset indent .It Single process can own multiple kernel threads (LWPs). .It Process possesses address space context to map userland address space. .It Processes are designed for userland executables and kernel threads for in-kernel tasks. The only process running in the kernel-space is .Dv proc0 (called swapper). .El .Sh INTERFACES The .Nx kernel is written to run across multiple unicore and multicore CPUs. The following lists lists alphabetically. .Ss Atomic memory operations The .Nm atomic_ops family of functions provide atomic memory operations. There are 7 classes of atomic memory operations available: addition, logical .Dq and , compare-and-swap, decrement, increment, logical .Dq or , swap. .Pp See .Xr atomic_ops 3 . .Ss Condition variables Condition variables (CVs) are used in the kernel to synchronize access to resources that are limited (for example, memory) and to wait for pending I/O operations to complete. .Pp See .Xr condvar 9 . .Ss Memory access barrier operations The .Nm membar_ops family of functions provide memory access barrier operations necessary for synchronization in multiprocessor execution environments that have relaxed load and store order. .Pp See .Xr membar_ops 3 . .Ss Memory barriers The memory barriers can be used to control the order in which memory accesses occur, and thus the order in which those accesses become visible to other processors. They can be used to implement .Dq lockless access to data structures where the necessary barrier conditions are well understood. .Pp See .Xr mb 9 . .Ss Mutual exclusion primitives Thread-base adaptive mutexes. These are lightweight, exclusive locks that use threads as the focus of synchronization activity. Adaptive mutexes typically behave like spinlock, but under specific conditions an attempt to acquire an already held adaptive mutex may cause the acquiring thread to sleep. Sleep activity occurs rarely. Busy-waiting is typically more efficient because mutex hold times are most often short. In contrast to pure spinlocks, a thread holding an adaptive mutex may be preempted in the kernel, which can allow for reduced latency where soft real-time application are in use on the system. .Pp See .Xr mutex 9 . .Ss Restartable atomic sequences Restartable atomic sequences are user code only sequences which are guaranteed to execute without preemption. This property is assured by checking the set of restartable atomic sequences registered for a process during .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). .Pp See .Xr ras 9 . .Ss Reader / writer lock primitives Reader / writer locks (RW locks) are used in the kernel to synchronize access to an object among LWPs (lightweight processes) and soft interrupt handlers. In addition to the capabilities provided by mutexes, RW locks distinguish between read (shared) and write (exclusive) access. .Pp See .Xr rwlock 9 . .Ss Functions to modify system interrupt priority level These functions raise and lower the interrupt priority level. They are used by kernel code to block interrupts in critical sections, in order to protect data structures. .Pp See .Xr spl 9 . .Ss Machine-independent software interrupt framework The software interrupt framework is designed to provide a generic software interrupt mechanism which can be used any time a low-priority callback is needed. It allows dynamic registration of software interrupts for loadable drivers and protocol stacks, prioritization and fair queueing of software interrupts, and allows machine-dependent optimizations to reduce cost. .Pp See .Xr softint 9 . .Ss Functions to raise the system priority level The .Nm splraiseipl function raises the system priority level to the level specified by .Dv icookie , which should be a value returned by .Xr makeiplcookie 9 . In general, device drivers should not make use of this interface. To ensure correct synchronization, device drivers should use the .Xr condvar 9 , .Xr mutex 9 , and .Xr rwlock 9 interfaces. .Pp See .Xr splraiseipl 9 . .Ss Passive serialization mechanism Passive serialization is a reader / writer synchronisation mechanism designed for lock-less read operations. The read operations may happen from software interrupt at .Dv IPL_SOFTCLOCK . .Pp See .Xr pserialize 9 . .Ss Simple do-it-in-thread-context framework The workqueue utility routines are provided to defer work which is needed to be processed in a thread context. .Pp See .Xr workqueue 9 . .Sh USAGE The following table describes legal usage of the .Nx interfaces in different contexts. The synchronization primitives available in more then one context can be used to protect shared resources between these overlapping contexts. .Bl -column -offset indent \ "xxxxxxxxxxxx " "xxxxxxx " "xxxxxxx " "xxxxxxx " .It Sy interface Ta Sy thread Ta Sy softirq Ta Sy hardirq .It Xr atomic_ops 3 Ta yes Ta yes Ta yes .It Xr condvar 9 Ta yes Ta partly Ta no .It Xr mb 9 Ta yes Ta yes Ta yes .It Xr membar_ops 3 Ta yes Ta yes Ta yes .It Xr mutex 9 Ta yes Ta depends Ta depends .It Xr rwlock 9 Ta yes Ta yes Ta no .It Xr softint 9 Ta yes Ta yes Ta yes .It Xr spl 9 Ta yes Ta no Ta no .It Xr splraiseipl 9 Ta yes Ta no Ta no .It Xr pserialize 9 Ta yes Ta yes Ta no .It Xr workqueue 9 Ta yes Ta yes Ta yes .El .Sh SEE ALSO .Xr atomic_ops 3 , .Xr membar_ops 3 , .Xr condvar 9 , .Xr mb 9 , .Xr mutex 9 , .Xr ras 9 , .Xr rwlock 9 , .Xr softint 9 , .Xr splraiseipl 9 , .Xr spl 9 , .Xr workqueue 9 .Sh HISTORY The initial SMP support was introduced in the .Nx 2.0 and was designed with the giant kernel lock. Through .Nx 4.0 , the kernel used spinlocks and a per-CPU interrupt priority level (the .Xr spl 9 system). These mechanisms did not lend themselves well to a multiprocessor environment supporting kernel preemption. The use of thread based (lock) synchronization was limited and the available 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. .Pp This file first appeared in .Nx 8.0 and was inspired by the corresponding .Xr locking 9 manpages from .Fx and .Dx . Already existing documentation was used to compile this manpage. .Sh AUTHORS .An Kamil Rytarowski