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 May 12, 2016
  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_testandclear_<type> "volatile <type> *p" "u_int v"
  69 .Ft int
  70 .Fn atomic_testandset_<type> "volatile <type> *p" "u_int v"
  71 .Sh DESCRIPTION
  72 Each of the atomic operations is guaranteed to be atomic across multiple
  73 threads and in the presence of interrupts.
  74 They can be used to implement reference counts or as building blocks for more
  75 advanced synchronization primitives such as mutexes.
  76 .Ss Types
  77 Each atomic operation operates on a specific
  78 .Fa type .
  79 The type to use is indicated in the function name.
  80 The available types that can be used are:
  81 .Pp
  82 .Bl -tag -offset indent -width short -compact
  83 .It Li int
  84 unsigned integer
  85 .It Li long
  86 unsigned long integer
  87 .It Li ptr
  88 unsigned integer the size of a pointer
  89 .It Li 32
  90 unsigned 32-bit integer
  91 .It Li 64
  92 unsigned 64-bit integer
  93 .El
  94 .Pp
  95 For example, the function to atomically add two integers is called
  96 .Fn atomic_add_int .
  97 .Pp
  98 Certain architectures also provide operations for types smaller than
  99 .Dq Li int .
 100 .Pp
 101 .Bl -tag -offset indent -width short -compact
 102 .It Li char
 103 unsigned character
 104 .It Li short
 105 unsigned short integer
 106 .It Li 8
 107 unsigned 8-bit integer
 108 .It Li 16
 109 unsigned 16-bit integer
 110 .El
 111 .Pp
 112 These must not be used in MI code because the instructions to implement them
 113 efficiently might not be available.
 114 .Ss Acquire and Release Operations
 115 By default, a thread's accesses to different memory locations might not be
 116 performed in
 117 .Em program order ,
 118 that is, the order in which the accesses appear in the source code.
 119 To optimize the program's execution, both the compiler and processor might
 120 reorder the thread's accesses.
 121 However, both ensure that their reordering of the accesses is not visible to
 122 the thread.
 123 Otherwise, the traditional memory model that is expected by single-threaded
 124 programs would be violated.
 125 Nonetheless, other threads in a multithreaded program, such as the
 126 .Fx
 127 kernel, might observe the reordering.
 128 Moreover, in some cases, such as the implementation of synchronization between
 129 threads, arbitrary reordering might result in the incorrect execution of the
 130 program.
 131 To constrain the reordering that both the compiler and processor might perform
 132 on a thread's accesses, the thread should use atomic operations with
 133 .Em acquire
 134 and
 135 .Em release
 136 semantics.
 137 .Pp
 138 Most of the atomic operations on memory have three variants.
 139 The first variant performs the operation without imposing any ordering
 140 constraints on memory accesses to other locations.
 141 The second variant has acquire semantics, and the third variant has release
 142 semantics.
 143 In effect, operations with acquire and release semantics establish one-way
 144 barriers to reordering.
 145 .Pp
 146 When an atomic operation has acquire semantics, the effects of the operation
 147 must have completed before any subsequent load or store (by program order) is
 148 performed.
 149 Conversely, acquire semantics do not require that prior loads or stores have
 150 completed before the atomic operation is performed.
 151 To denote acquire semantics, the suffix
 152 .Dq Li _acq
 153 is inserted into the function name immediately prior to the
 154 .Dq Li _ Ns Aq Fa type
 155 suffix.
 156 For example, to subtract two integers ensuring that subsequent loads and
 157 stores happen after the subtraction is performed, use
 158 .Fn atomic_subtract_acq_int .
 159 .Pp
 160 When an atomic operation has release semantics, the effects of all prior
 161 loads or stores (by program order) must have completed before the operation
 162 is performed.
 163 Conversely, release semantics do not require that the effects of the
 164 atomic operation must have completed before any subsequent load or store is
 165 performed.
 166 To denote release semantics, the suffix
 167 .Dq Li _rel
 168 is inserted into the function name immediately prior to the
 169 .Dq Li _ Ns Aq Fa type
 170 suffix.
 171 For example, to add two long integers ensuring that all prior loads and
 172 stores happen before the addition, use
 173 .Fn atomic_add_rel_long .
 174 .Pp
 175 The one-way barriers provided by acquire and release operations allow the
 176 implementations of common synchronization primitives to express their
 177 ordering requirements without also imposing unnecessary ordering.
 178 For example, for a critical section guarded by a mutex, an acquire operation
 179 when the mutex is locked and a release operation when the mutex is unlocked
 180 will prevent any loads or stores from moving outside of the critical
 181 section.
 182 However, they will not prevent the compiler or processor from moving loads
 183 or stores into the critical section, which does not violate the semantics of
 184 a mutex.
 185 .Ss Multiple Processors
 186 In multiprocessor systems, the atomicity of the atomic operations on memory
 187 depends on support for cache coherence in the underlying architecture.
 188 In general, cache coherence on the default memory type,
 189 .Dv VM_MEMATTR_DEFAULT ,
 190 is guaranteed by all architectures that are supported by
 191 .Fx .
 192 For example, cache coherence is guaranteed on write-back memory by the
 193 .Tn amd64
 194 and
 195 .Tn i386
 196 architectures.
 197 However, on some architectures, cache coherence might not be enabled on all
 198 memory types.
 199 To determine if cache coherence is enabled for a non-default memory type,
 200 consult the architecture's documentation.
 201 On the
 202 .Tn ia64
 203 architecture, coherency is only guaranteed for pages that are configured to
 204 using a caching policy of either uncached or write back.
 205 .Ss Semantics
 206 This section describes the semantics of each operation using a C like notation.
 207 .Bl -hang
 208 .It Fn atomic_add p v
 209 .Bd -literal -compact
 210 *p += v;
 211 .Ed
 212 .It Fn atomic_clear p v
 213 .Bd -literal -compact
 214 *p &= ~v;
 215 .Ed
 216 .It Fn atomic_cmpset dst old new
 217 .Bd -literal -compact
 218 if (*dst == old) {
 219         *dst = new;
 220         return (1);
 221 } else
 222         return (0);
 223 .Ed
 224 .El
 225 .Pp
 226 The
 227 .Fn atomic_cmpset
 228 functions are not implemented for the types
 229 .Dq Li char ,
 230 .Dq Li short ,
 231 .Dq Li 8 ,
 232 and
 233 .Dq Li 16 .
 234 .Bl -hang
 235 .It Fn atomic_fetchadd p v
 236 .Bd -literal -compact
 237 tmp = *p;
 238 *p += v;
 239 return (tmp);
 240 .Ed
 241 .El
 242 .Pp
 243 The
 244 .Fn atomic_fetchadd
 245 functions are only implemented for the types
 246 .Dq Li int ,
 247 .Dq Li long
 248 and
 249 .Dq Li 32
 250 and do not have any variants with memory barriers at this time.
 251 .Bl -hang
 252 .It Fn atomic_load p
 253 .Bd -literal -compact
 254 return (*p);
 255 .Ed
 256 .El
 257 .Pp
 258 The
 259 .Fn atomic_load
 260 functions are only provided with acquire memory barriers.
 261 .Bl -hang
 262 .It Fn atomic_readandclear p
 263 .Bd -literal -compact
 264 tmp = *p;
 265 *p = 0;
 266 return (tmp);
 267 .Ed
 268 .El
 269 .Pp
 270 The
 271 .Fn atomic_readandclear
 272 functions are not implemented for the types
 273 .Dq Li char ,
 274 .Dq Li short ,
 275 .Dq Li ptr ,
 276 .Dq Li 8 ,
 277 and
 278 .Dq Li 16
 279 and do not have any variants with memory barriers at this time.
 280 .Bl -hang
 281 .It Fn atomic_set p v
 282 .Bd -literal -compact
 283 *p |= v;
 284 .Ed
 285 .It Fn atomic_subtract p v
 286 .Bd -literal -compact
 287 *p -= v;
 288 .Ed
 289 .It Fn atomic_store p v
 290 .Bd -literal -compact
 291 *p = v;
 292 .Ed
 293 .El
 294 .Pp
 295 The
 296 .Fn atomic_store
 297 functions are only provided with release memory barriers.
 298 .Bl -hang
 299 .It Fn atomic_swap p v
 300 .Bd -literal -compact
 301 tmp = *p;
 302 *p = v;
 303 return (tmp);
 304 .Ed
 305 .El
 306 .Pp
 307 The
 308 .Fn atomic_swap
 309 functions are not implemented for the types
 310 .Dq Li char ,
 311 .Dq Li short ,
 312 .Dq Li ptr ,
 313 .Dq Li 8 ,
 314 and
 315 .Dq Li 16
 316 and do not have any variants with memory barriers at this time.
 317 .Bl -hang
 318 .It Fn atomic_testandclear p v
 319 .Bd -literal -compact
 320 bit = 1 << (v % (sizeof(*p) * NBBY));
 321 tmp = (*p & bit) != 0;
 322 *p &= ~bit;
 323 return (tmp);
 324 .Ed
 325 .El
 326 .Bl -hang
 327 .It Fn atomic_testandset p v
 328 .Bd -literal -compact
 329 bit = 1 << (v % (sizeof(*p) * NBBY));
 330 tmp = (*p & bit) != 0;
 331 *p |= bit;
 332 return (tmp);
 333 .Ed
 334 .El
 335 .Pp
 336 The
 337 .Fn atomic_testandset
 338 and
 339 .Fn atomic_testandclear
 340 functions are only implemented for the types
 341 .Dq Li int ,
 342 .Dq Li long
 343 and
 344 .Dq Li 32
 345 and do not have any variants with memory barriers at this time.
 346 .Pp
 347 The type
 348 .Dq Li 64
 349 is currently not implemented for any of the atomic operations on the
 350 .Tn arm ,
 351 .Tn i386 ,
 352 and
 353 .Tn powerpc
 354 architectures.
 355 .Sh RETURN VALUES
 356 The
 357 .Fn atomic_cmpset
 358 function returns the result of the compare operation.
 359 The
 360 .Fn atomic_fetchadd ,
 361 .Fn atomic_load ,
 362 .Fn atomic_readandclear ,
 363 and
 364 .Fn atomic_swap
 365 functions return the value at the specified address.
 366 The
 367 .Fn atomic_testandset
 368 and
 369 .Fn atomic_testandclear
 370 function returns the result of the test operation.
 371 .Sh EXAMPLES
 372 This example uses the
 373 .Fn atomic_cmpset_acq_ptr
 374 and
 375 .Fn atomic_set_ptr
 376 functions to obtain a sleep mutex and handle recursion.
 377 Since the
 378 .Va mtx_lock
 379 member of a
 380 .Vt "struct mtx"
 381 is a pointer, the
 382 .Dq Li ptr
 383 type is used.
 384 .Bd -literal
 385 /* Try to obtain mtx_lock once. */
 386 #define _obtain_lock(mp, tid)                                           \\
 387         atomic_cmpset_acq_ptr(&(mp)->mtx_lock, MTX_UNOWNED, (tid))
 388
 389 /* Get a sleep lock, deal with recursion inline. */
 390 #define _get_sleep_lock(mp, tid, opts, file, line) do {                 \\
 391         uintptr_t _tid = (uintptr_t)(tid);                              \\
 392                                                                         \\
 393         if (!_obtain_lock(mp, tid)) {                                   \\
 394                 if (((mp)->mtx_lock & MTX_FLAGMASK) != _tid)            \\
 395                         _mtx_lock_sleep((mp), _tid, (opts), (file), (line));\\
 396                 else {                                                  \\
 397                         atomic_set_ptr(&(mp)->mtx_lock, MTX_RECURSE);   \\
 398                         (mp)->mtx_recurse++;                            \\
 399                 }                                                       \\
 400         }                                                               \\
 401 } while (0)
 402 .Ed
 403 .Sh HISTORY
 404 The
 405 .Fn atomic_add ,
 406 .Fn atomic_clear ,
 407 .Fn atomic_set ,
 408 and
 409 .Fn atomic_subtract
 410 operations were first introduced in
 411 .Fx 3.0 .
 412 This first set only supported the types
 413 .Dq Li char ,
 414 .Dq Li short ,
 415 .Dq Li int ,
 416 and
 417 .Dq Li long .
 418 The
 419 .Fn atomic_cmpset ,
 420 .Fn atomic_load ,
 421 .Fn atomic_readandclear ,
 422 and
 423 .Fn atomic_store
 424 operations were added in
 425 .Fx 5.0 .
 426 The types
 427 .Dq Li 8 ,
 428 .Dq Li 16 ,
 429 .Dq Li 32 ,
 430 .Dq Li 64 ,
 431 and
 432 .Dq Li ptr
 433 and all of the acquire and release variants
 434 were added in
 435 .Fx 5.0
 436 as well.
 437 The
 438 .Fn atomic_fetchadd
 439 operations were added in
 440 .Fx 6.0 .
 441 The
 442 .Fn atomic_swap
 443 and
 444 .Fn atomic_testandset
 445 operations were added in
 446 .Fx 10.0 .
 447 .Fn atomic_testandclear
 448 operation was added in
 449 .Fx 11.0 .