Atomic test and set patches (was Re: ppp and other problems)

Richard Henderson (richard@atheist.tamu.edu)
Sun, 1 Sep 1996 03:04:00 -0500 (CDT)


Steve Blackburn wrote:
> The problem is that ppp.c uses set_bit, which is word-based, to set
> byte values. This is a clear bug -- however, it works OK (by good
> luck) on the little endian machines, as only the least significant bit
> is touched. On a big endian machine things don't work out so well
> :-). My temorary hack is to add set_bit_byte and get_bit_byte
> routines (thanks to Tridge for helping me get the bug out a few weeks
> ago).

It seems clear to me that things would be much cleaner with a real
test and set routine instead of using set_bit(0,...) directly. It
also happens that we can actually do this atomically on the Sparc
without resorting to turning off interrupts.

The following patch adds such a test and set primitive to <asm/atomic.h>
for platforms I am familiar with, and in all places I could identify
that a set_bit(0,...) was used as a lone flag, made the appropriate
modifications.

The t&s primitive is simply defined to set the argument to non-zero
(not 1!). This also means that for proper operation, the only two
values that can safely be assigned to such a lock are 0 and -1; using
1 is not sufficient, because, e.g., on m68k and sparc the high-order
bit(s) is set and the low-order bit is not examined at all.

To the i386 users, can yall check that I didn't make any typos in
your drivers, and check that I didn't miss any 1 -> -1 changes?

r~
------
begin 664 testandset.patch.gz
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
Steve Blackburn wrote:
> The problem is that ppp.c uses set_bit, which is word-based, to set
> byte values. This is a clear bug -- however, it works OK (by good
> luck) on the little endian machines, as only the least significant bit
> is touched. On a big endian machine things don't work out so well
> :-). My temorary hack is to add set_bit_byte and get_bit_byte
> routines (thanks to Tridge for helping me get the bug out a few weeks
> ago).

It seems clear to me that things would be much cleaner with a real
test and set routine instead of using set_bit(0,...) directly. It
also happens that we can actually do this atomically on the Sparc
without resorting to turning off interrupts.

The following patch adds such a test and set primitive to <asm/atomic.h>
for platforms I am familiar with, and in all places I could identify
that a set_bit(0,...) was used as a lone flag, made the appropriate
modifications.

The t&s primitive is simply defined to set the argument to non-zero
(not 1!). This also means that for proper operation, the only two
values that can safely be assigned to such a lock are 0 and -1; using
1 is not sufficient, because, e.g., on m68k and sparc the high-order
bit(s) is set and the low-order bit is not examined at all.

To the i386 users, can yall check that I didn't make any typos in
your drivers, and check that I didn't miss any 1 -> -1 changes?

r~
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
8MKH,KTDI2W/Z+\J,C6O_!TE^Q*V6!@$`
`
end