share/man/man9/atomic.9

   1 .\" Copyright (c) 2000-2001 John H. Baldwin <jhb@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  14 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  15 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  16 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  17 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  18 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  19 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  20 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  21 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  22 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd August 14, 2015
  27 .Dt ATOMIC 9
  28 .Os
  29 .Sh NAME
  30 .Nm atomic_add ,
  31 .Nm atomic_clear ,
  32 .Nm atomic_cmpset ,
  33 .Nm atomic_fetchadd ,
  34 .Nm atomic_load ,
  35 .Nm atomic_readandclear ,
  36 .Nm atomic_set ,
  37 .Nm atomic_subtract ,
  38 .Nm atomic_store
  39 .Nd atomic operations
  40 .Sh SYNOPSIS
  41 .In sys/types.h
  42 .In machine/atomic.h
  43 .Ft void
  44 .Fn atomic_add_[acq_|rel_]<type> "volatile <type> *p" "<type> v"
  45 .Ft void
  46 .Fn atomic_clear_[acq_|rel_]<type> "volatile <type> *p" "<type> v"
  47 .Ft int
  48 .Fo atomic_cmpset_[acq_|rel_]<type>
  49 .Fa "volatile <type> *dst"
  50 .Fa "<type> old"
  51 .Fa "<type> new"
  52 .Fc
  53 .Ft <type>
  54 .Fn atomic_fetchadd_<type> "volatile <type> *p" "<type> v"
  55 .Ft <type>
  56 .Fn atomic_load_acq_<type> "volatile <type> *p"
  57 .Ft <type>
  58 .Fn atomic_readandclear_<type> "volatile <type> *p"
  59 .Ft void
  60 .Fn atomic_set_[acq_|rel_]<type> "volatile <type> *p" "<type> v"
  61 .Ft void
  62 .Fn atomic_subtract_[acq_|rel_]<type> "volatile <type> *p" "<type> v"
  63 .Ft void
  64 .Fn atomic_store_rel_<type> "volatile <type> *p" "<type> v"
  65 .Ft <type>
  66 .Fn atomic_swap_<type> "volatile <type> *p" "<type> v"
  67 .Ft int
  68 .Fn atomic_testandset_<type> "volatile <type> *p" "u_int v"
  69 .Sh DESCRIPTION
  70 Each of the atomic operations is guaranteed to be atomic across multiple
  71 threads and in the presence of interrupts.
  72 They can be used to implement reference counts or as building blocks for more
  73 advanced synchronization primitives such as mutexes.
  74 .Ss Types
  75 Each atomic operation operates on a specific
  76 .Fa type .
  77 The type to use is indicated in the function name.
  78 The available types that can be used are:
  79 .Pp
  80 .Bl -tag -offset indent -width short -compact
  81 .It Li int
  82 unsigned integer
  83 .It Li long
  84 unsigned long integer
  85 .It Li ptr
  86 unsigned integer the size of a pointer
  87 .It Li 32
  88 unsigned 32-bit integer
  89 .It Li 64
  90 unsigned 64-bit integer
  91 .El
  92 .Pp
  93 For example, the function to atomically add two integers is called
  94 .Fn atomic_add_int .
  95 .Pp
  96 Certain architectures also provide operations for types smaller than
  97 .Dq Li int .
  98 .Pp
  99 .Bl -tag -offset indent -width short -compact
 100 .It Li char
 101 unsigned character
 102 .It Li short
 103 unsigned short integer
 104 .It Li 8
 105 unsigned 8-bit integer
 106 .It Li 16
 107 unsigned 16-bit integer
 108 .El
 109 .Pp
 110 These must not be used in MI code because the instructions to implement them
 111 efficiently might not be available.
 112 .Ss Acquire and Release Operations
 113 By default, a thread's accesses to different memory locations might not be
 114 performed in
 115 .Em program order ,
 116 that is, the order in which the accesses appear in the source code.
 117 To optimize the program's execution, both the compiler and processor might
 118 reorder the thread's accesses.
 119 However, both ensure that their reordering of the accesses is not visible to
 120 the thread.
 121 Otherwise, the traditional memory model that is expected by single-threaded
 122 programs would be violated.
 123 Nonetheless, other threads in a multithreaded program, such as the
 124 .Fx
 125 kernel, might observe the reordering.
 126 Moreover, in some cases, such as the implementation of synchronization between
 127 threads, arbitrary reordering might result in the incorrect execution of the
 128 program.
 129 To constrain the reordering that both the compiler and processor might perform
 130 on a thread's accesses, the thread should use atomic operations with
 131 .Em acquire
 132 and
 133 .Em release
 134 semantics.
 135 .Pp
 136 Most of the atomic operations on memory have three variants.
 137 The first variant performs the operation without imposing any ordering
 138 constraints on memory accesses to other locations.
 139 The second variant has acquire semantics, and the third variant has release
 140 semantics.
 141 In effect, operations with acquire and release semantics establish one-way
 142 barriers to reordering.
 143 .Pp
 144 When an atomic operation has acquire semantics, the effects of the operation
 145 must have completed before any subsequent load or store (by program order) is
 146 performed.
 147 Conversely, acquire semantics do not require that prior loads or stores have
 148 completed before the atomic operation is performed.
 149 To denote acquire semantics, the suffix
 150 .Dq Li _acq
 151 is inserted into the function name immediately prior to the
 152 .Dq Li _ Ns Aq Fa type
 153 suffix.
 154 For example, to subtract two integers ensuring that subsequent loads and
 155 stores happen after the subtraction is performed, use
 156 .Fn atomic_subtract_acq_int .
 157 .Pp
 158 When an atomic operation has release semantics, the effects of all prior
 159 loads or stores (by program order) must have completed before the operation
 160 is performed.
 161 Conversely, release semantics do not require that the effects of the
 162 atomic operation must have completed before any subsequent load or store is
 163 performed.
 164 To denote release semantics, the suffix
 165 .Dq Li _rel
 166 is inserted into the function name immediately prior to the
 167 .Dq Li _ Ns Aq Fa type
 168 suffix.
 169 For example, to add two long integers ensuring that all prior loads and
 170 stores happen before the addition, use
 171 .Fn atomic_add_rel_long .
 172 .Pp
 173 The one-way barriers provided by acquire and release operations allow the
 174 implementations of common synchronization primitives to express their
 175 ordering requirements without also imposing unnecessary ordering.
 176 For example, for a critical section guarded by a mutex, an acquire operation
 177 when the mutex is locked and a release operation when the mutex is unlocked
 178 will prevent any loads or stores from moving outside of the critical
 179 section.
 180 However, they will not prevent the compiler or processor from moving loads
 181 or stores into the critical section, which does not violate the semantics of
 182 a mutex.
 183 .Ss Multiple Processors
 184 In multiprocessor systems, the atomicity of the atomic operations on memory
 185 depends on support for cache coherence in the underlying architecture.
 186 In general, cache coherence on the default memory type,
 187 .Dv VM_MEMATTR_DEFAULT ,
 188 is guaranteed by all architectures that are supported by
 189 .Fx .
 190 For example, cache coherence is guaranteed on write-back memory by the
 191 .Tn amd64
 192 and
 193 .Tn i386
 194 architectures.
 195 However, on some architectures, cache coherence might not be enabled on all
 196 memory types.
 197 To determine if cache coherence is enabled for a non-default memory type,
 198 consult the architecture's documentation.
 199 On the
 200 .Tn ia64
 201 architecture, coherency is only guaranteed for pages that are configured to
 202 using a caching policy of either uncached or write back.
 203 .Ss Semantics
 204 This section describes the semantics of each operation using a C like notation.
 205 .Bl -hang
 206 .It Fn atomic_add p v
 207 .Bd -literal -compact
 208 *p += v;
 209 .Ed
 210 .It Fn atomic_clear p v
 211 .Bd -literal -compact
 212 *p &= ~v;
 213 .Ed
 214 .It Fn atomic_cmpset dst old new
 215 .Bd -literal -compact
 216 if (*dst == old) {
 217         *dst = new;
 218         return (1);
 219 } else
 220         return (0);
 221 .Ed
 222 .El
 223 .Pp
 224 The
 225 .Fn atomic_cmpset
 226 functions are not implemented for the types
 227 .Dq Li char ,
 228 .Dq Li short ,
 229 .Dq Li 8 ,
 230 and
 231 .Dq Li 16 .
 232 .Bl -hang
 233 .It Fn atomic_fetchadd p v
 234 .Bd -literal -compact
 235 tmp = *p;
 236 *p += v;
 237 return (tmp);
 238 .Ed
 239 .El
 240 .Pp
 241 The
 242 .Fn atomic_fetchadd
 243 functions are only implemented for the types
 244 .Dq Li int ,
 245 .Dq Li long
 246 and
 247 .Dq Li 32
 248 and do not have any variants with memory barriers at this time.
 249 .Bl -hang
 250 .It Fn atomic_load p
 251 .Bd -literal -compact
 252 return (*p);
 253 .Ed
 254 .El
 255 .Pp
 256 The
 257 .Fn atomic_load
 258 functions are only provided with acquire memory barriers.
 259 .Bl -hang
 260 .It Fn atomic_readandclear p
 261 .Bd -literal -compact
 262 tmp = *p;
 263 *p = 0;
 264 return (tmp);
 265 .Ed
 266 .El
 267 .Pp
 268 The
 269 .Fn atomic_readandclear
 270 functions are not implemented for the types
 271 .Dq Li char ,
 272 .Dq Li short ,
 273 .Dq Li ptr ,
 274 .Dq Li 8 ,
 275 and
 276 .Dq Li 16
 277 and do not have any variants with memory barriers at this time.
 278 .Bl -hang
 279 .It Fn atomic_set p v
 280 .Bd -literal -compact
 281 *p |= v;
 282 .Ed
 283 .It Fn atomic_subtract p v
 284 .Bd -literal -compact
 285 *p -= v;
 286 .Ed
 287 .It Fn atomic_store p v
 288 .Bd -literal -compact
 289 *p = v;
 290 .Ed
 291 .El
 292 .Pp
 293 The
 294 .Fn atomic_store
 295 functions are only provided with release memory barriers.
 296 .Bl -hang
 297 .It Fn atomic_swap p v
 298 .Bd -literal -compact
 299 tmp = *p;
 300 *p = v;
 301 return (tmp);
 302 .Ed
 303 .El
 304 .Pp
 305 The
 306 .Fn atomic_swap
 307 functions are not implemented for the types
 308 .Dq Li char ,
 309 .Dq Li short ,
 310 .Dq Li ptr ,
 311 .Dq Li 8 ,
 312 and
 313 .Dq Li 16
 314 and do not have any variants with memory barriers at this time.
 315 .Bl -hang
 316 .It Fn atomic_testandset p v
 317 .Bd -literal -compact
 318 bit = 1 << (v % (sizeof(*p) * NBBY));
 319 tmp = (*p & bit) != 0;
 320 *p |= bit;
 321 return (tmp);
 322 .Ed
 323 .El
 324 .Pp
 325 The
 326 .Fn atomic_testandset
 327 functions are only implemented for the types
 328 .Dq Li int ,
 329 .Dq Li long
 330 and
 331 .Dq Li 32
 332 and do not have any variants with memory barriers at this time.
 333 .Pp
 334 The type
 335 .Dq Li 64
 336 is currently not implemented for any of the atomic operations on the
 337 .Tn arm ,
 338 .Tn i386 ,
 339 and
 340 .Tn powerpc
 341 architectures.
 342 .Sh RETURN VALUES
 343 The
 344 .Fn atomic_cmpset
 345 function returns the result of the compare operation.
 346 The
 347 .Fn atomic_fetchadd ,
 348 .Fn atomic_load ,
 349 .Fn atomic_readandclear ,
 350 and
 351 .Fn atomic_swap
 352 functions return the value at the specified address.
 353 The
 354 .Fn atomic_testandset
 355 function returns the result of the test operation.
 356 .Sh EXAMPLES
 357 This example uses the
 358 .Fn atomic_cmpset_acq_ptr
 359 and
 360 .Fn atomic_set_ptr
 361 functions to obtain a sleep mutex and handle recursion.
 362 Since the
 363 .Va mtx_lock
 364 member of a
 365 .Vt "struct mtx"
 366 is a pointer, the
 367 .Dq Li ptr
 368 type is used.
 369 .Bd -literal
 370 /* Try to obtain mtx_lock once. */
 371 #define _obtain_lock(mp, tid)                                           \\
 372         atomic_cmpset_acq_ptr(&(mp)->mtx_lock, MTX_UNOWNED, (tid))
 373
 374 /* Get a sleep lock, deal with recursion inline. */
 375 #define _get_sleep_lock(mp, tid, opts, file, line) do {                 \\
 376         uintptr_t _tid = (uintptr_t)(tid);                              \\
 377                                                                         \\
 378         if (!_obtain_lock(mp, tid)) {                                   \\
 379                 if (((mp)->mtx_lock & MTX_FLAGMASK) != _tid)            \\
 380                         _mtx_lock_sleep((mp), _tid, (opts), (file), (line));\\
 381                 else {                                                  \\
 382                         atomic_set_ptr(&(mp)->mtx_lock, MTX_RECURSE);   \\
 383                         (mp)->mtx_recurse++;                            \\
 384                 }                                                       \\
 385         }                                                               \\
 386 } while (0)
 387 .Ed
 388 .Sh HISTORY
 389 The
 390 .Fn atomic_add ,
 391 .Fn atomic_clear ,
 392 .Fn atomic_set ,
 393 and
 394 .Fn atomic_subtract
 395 operations were first introduced in
 396 .Fx 3.0 .
 397 This first set only supported the types
 398 .Dq Li char ,
 399 .Dq Li short ,
 400 .Dq Li int ,
 401 and
 402 .Dq Li long .
 403 The
 404 .Fn atomic_cmpset ,
 405 .Fn atomic_load ,
 406 .Fn atomic_readandclear ,
 407 and
 408 .Fn atomic_store
 409 operations were added in
 410 .Fx 5.0 .
 411 The types
 412 .Dq Li 8 ,
 413 .Dq Li 16 ,
 414 .Dq Li 32 ,
 415 .Dq Li 64 ,
 416 and
 417 .Dq Li ptr
 418 and all of the acquire and release variants
 419 were added in
 420 .Fx 5.0
 421 as well.
 422 The
 423 .Fn atomic_fetchadd
 424 operations were added in
 425 .Fx 6.0 .
 426 The
 427 .Fn atomic_swap
 428 and
 429 .Fn atomic_testandset
 430 operations were added in
 431 .Fx 10.0 .