share/man/man9/mb.9

   1 .\"     $NetBSD: mb.9,v 1.4 2007/12/01 19:59:05 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2007 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Andrew Doran.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd April 8, 2007
  31 .Dt MB 9
  32 .Os
  33 .Sh NAME
  34 .Nm mb ,
  35 .Nm mb_memory ,
  36 .Nm mb_read ,
  37 .Nm mb_write
  38 .Nd memory barriers
  39 .Sh SYNOPSIS
  40 .In sys/lock.h
  41 .Ft void
  42 .Fn mb_memory "void"
  43 .Ft void
  44 .Fn mb_read "void"
  45 .Ft void
  46 .Fn mb_write "void"
  47 .Sh DESCRIPTION
  48 Many types of processor can execute instructions in a different order
  49 than issued by the compiler or assembler.
  50 On a uniprocessor system, out of order execution is transparent
  51 to the programmer, operating system and applications, as the processor
  52 must ensure that it is self consistent.
  53 .Pp
  54 On multiprocessor systems, out of order execution can present a
  55 problem where locks are not used to guarantee atomicity of
  56 access, because loads and stores issued by any given processor
  57 can appear on the system bus (and thus appear to other processors)
  58 in an unpredictable order.
  59 .Pp
  60 .Fn mb_memory ,
  61 .Fn mb_read ,
  62 and
  63 .Fn mb_write
  64 can be used to control the order in which memory accesses occur, and
  65 thus the order in which those accesses become visible to other processors.
  66 They can be used to implement
  67 .Dq lockless
  68 access to data structures where
  69 the necessary barrier conditions are well understood.
  70 .Pp
  71 Memory barriers can be computationally expensive, as they are
  72 considered
  73 .Dq serializing
  74 operations and may stall further execution
  75 until the processor has drained internal buffers and re-synchronized.
  76 .Pp
  77 The memory barrier primitives control only the order of memory access.
  78 They provide no guarantee that stores have been flushed to the bus, or
  79 that loads have been made from the bus.
  80 .Pp
  81 The memory barrier primitives are guaranteed only to prevent reordering
  82 of accesses to main memory.
  83 They do not provide any guarantee of ordering when used with device
  84 memory (for example, loads or stores to or from a PCI device).
  85 To guarantee ordering of access to device memory, the
  86 .Xr bus_dma 9
  87 and
  88 .Xr bus_space 9
  89 interfaces should be used.
  90 .Sh FUNCTIONS
  91 .Bl -tag -width abcd
  92 .It Fn mb_memory ""
  93 .Pp
  94 Issue a full memory barrier, ordering all memory accesses.
  95 Causes all loads and stores preceding the call to
  96 .Fn mb_memory
  97 to complete before further memory accesses can be made.
  98 .It Fn mb_read ""
  99 .Pp
 100 Issue a read memory barrier, ordering all loads from memory.
 101 Causes all loads preceding the call to
 102 .Fn mb_read
 103 to complete before further loads can be made.
 104 Stores may be reordered ahead of or behind a call to
 105 .Fn mb_read .
 106 .It Fn mb_write ""
 107 .Pp
 108 Issue a write memory barrier, ordering all stores to memory.
 109 Causes all stores preceding the call to
 110 .Fn mb_write
 111 to complete before further stores can be made.
 112 Loads may be reordered ahead of or behind a call to
 113 .Fn mb_write .
 114 .El
 115 .Sh SEE ALSO
 116 .Xr bus_dma 9 ,
 117 .Xr bus_space 9 ,
 118 .Xr mutex 9 ,
 119 .Xr rwlock 9
 120 .Sh HISTORY
 121 The memory barrier primitives first appeared in
 122 .Nx 5.0 .