128 lines
4.3 KiB
Groff
128 lines
4.3 KiB
Groff
.\" $NetBSD: mb.9,v 1.8 2017/11/13 09:10:47 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2007 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Andrew Doran.
|
|
.\"
|
|
.\" 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 November 12, 2017
|
|
.Dt MB 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mb ,
|
|
.Nm mb_memory ,
|
|
.Nm mb_read ,
|
|
.Nm mb_write
|
|
.Nd memory barriers
|
|
.Sh SYNOPSIS
|
|
.In sys/lock.h
|
|
.Ft void
|
|
.Fn mb_memory "void"
|
|
.Ft void
|
|
.Fn mb_read "void"
|
|
.Ft void
|
|
.Fn mb_write "void"
|
|
.Sh DESCRIPTION
|
|
.Em The
|
|
.Nm
|
|
.Em API is deprecated; use
|
|
.Xr membar_ops 3
|
|
.Em instead .
|
|
.Pp
|
|
Many types of processor can execute instructions in a different order
|
|
than issued by the compiler or assembler.
|
|
On a uniprocessor system, out of order execution is transparent
|
|
to the programmer, operating system and applications, as the processor
|
|
must ensure that it is self consistent.
|
|
.Pp
|
|
On multiprocessor systems, out of order execution can present a
|
|
problem where locks are not used to guarantee atomicity of
|
|
access, because loads and stores issued by any given processor
|
|
can appear on the system bus (and thus appear to other processors)
|
|
in an unpredictable order.
|
|
.Pp
|
|
.Fn mb_memory ,
|
|
.Fn mb_read ,
|
|
and
|
|
.Fn mb_write
|
|
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
|
|
Memory barriers can be computationally expensive, as they are
|
|
considered
|
|
.Dq serializing
|
|
operations and may stall further execution
|
|
until the processor has drained internal buffers and re-synchronized.
|
|
.Pp
|
|
The memory barrier primitives control only the order of memory access.
|
|
They provide no guarantee that stores have been flushed to the bus, or
|
|
that loads have been made from the bus.
|
|
.Pp
|
|
The memory barrier primitives are guaranteed only to prevent reordering
|
|
of accesses to main memory.
|
|
They do not provide any guarantee of ordering when used with device
|
|
memory (for example, loads or stores to or from a PCI device).
|
|
To guarantee ordering of access to device memory, the
|
|
.Xr bus_dma 9
|
|
and
|
|
.Xr bus_space 9
|
|
interfaces should be used.
|
|
.Sh FUNCTIONS
|
|
.Bl -tag -width abcd
|
|
.It Fn mb_memory ""
|
|
Issue a full memory barrier, ordering all memory accesses.
|
|
Causes all loads and stores preceding the call to
|
|
.Fn mb_memory
|
|
to complete before further memory accesses can be made.
|
|
.It Fn mb_read ""
|
|
Issue a read memory barrier, ordering all loads from memory.
|
|
Causes all loads preceding the call to
|
|
.Fn mb_read
|
|
to complete before further loads can be made.
|
|
Stores may be reordered ahead of or behind a call to
|
|
.Fn mb_read .
|
|
.It Fn mb_write ""
|
|
Issue a write memory barrier, ordering all stores to memory.
|
|
Causes all stores preceding the call to
|
|
.Fn mb_write
|
|
to complete before further stores can be made.
|
|
Loads may be reordered ahead of or behind a call to
|
|
.Fn mb_write .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr __insn_barrier 3 ,
|
|
.Xr membar_ops 3 ,
|
|
.Xr bus_dma 9 ,
|
|
.Xr bus_space 9 ,
|
|
.Xr mutex 9 ,
|
|
.Xr rwlock 9
|
|
.Sh HISTORY
|
|
The memory barrier primitives first appeared in
|
|
.Nx 5.0 .
|