Date: Thu, 14 Jan 2016 18:28:56 -0500 From: Rich Felker <dalias@...c.org> To: musl@...ts.openwall.com Subject: Re: atomic primitives documentation On Thu, Jan 14, 2016 at 04:46:03PM -0500, Max Ruttenberg wrote: > Hi all, > > I'm trying to implement the atomic primitives but am finding the lack of > documentation (i.e. specifying what each one is supposed to do, which > argument is which, etc. ) a challenging obstacle. I've been googling around > and haven't found anything helpful. I could look at how it's used in the > source (that's what I've been doing so far) but it's cumbersome and I was > wondering if there was documentation somewhere that I just happen to be > missing. For all atomic primitives, the pointer argument (the first argument slot) is the address to operate on and the subsequent arguments are the values to work with. Unless mentioned otherwise, they all operate on 32-bit ints; only the _p (pointer), _l (long), and _64 (64-bit) versions operate on other types. All atomic ops are strong memory barriers. a_cas is an atomic compare-and-swap which compares against the value passed as the second ("test") argument and, if it matches, replaces with the value passed as the third ("set") argument. The return value is the old value read, which will be equal to the second argument on success, and equal to some other value that was actually observed in the case of failure. a_fetch_add atomically adds the value argument to the pointed-to object and returns the _old_ value. a_inc and a_dec are like a_fetch_add with values 1/-1, but they're not required to return the old value which makes them faster/simpler on some archs. a_and_64 and a_or_64 are misnamed; they're actually only usable as atomic bitset/bitclear since they're not necessarily atomic on the whole 64-bit unit. a_barrier is a memory barrier by itself with no actual atomic operation. a_spin is a cpu-relaxation & barrier operation to be used when spinning on an atomic. A few functions have nothing to do with "atomics" and are just in this file for no good reason except that they're arch-specific and usually written in asm: a_ctz_l/_64 (count trailing zeros) and a_crash (generate SIGSEGV or SIGILL termination as immediately as possible). If you want to do this the easy way, just implement a_cas and do everything else in terms of a_cas or with generic C code; see some of the existing archs for examples. Rich
Powered by blists - more mailing lists
Confused about mailing lists and their use? Read about mailing lists on Wikipedia and check out these guidelines on proper formatting of your messages.