Re: [PATCH] documentation: explain memory barriers

[Chris Snook <csnook@redhat.com>]

Andrew Morton wrote:
> On Wed, 08 Oct 2008 21:17:58 -0400 Chris Snook <csnook@redhat.com> wrote:
> 
>> Randy Dunlap wrote:
>>> On Wed, 1 Oct 2008 22:54:04 -0700 Andrew Morton wrote:
>>>
>>>> This sequence is repeated three or four times and should be pulled out
>>>> into a well-commented function.  That comment should explain the logic
>>>> behind the use of these barriers, please.
>>> and on 2008-OCT-08 Ben Hutchings wrote:
>>>
>>>> All memory barriers need a comment to explain why and what they're doing.
> 
> I approve this message.
> 
>> Seriously?  When a barrier is used, it's generally self-evident what 
>> it's doing.
> 
> fs/buffer.c:sync_buffer().  Have fun.

The real disaster there is the clear_buffer_##name macro and friends, as
evidenced by fs/ext2/inode.c:599

                clear_buffer_new(bh_result); /* What's this do? */

I'm completely in favor of documenting everything that can potentially interact
with that train wreck, but I maintain that the vast majority of memory barriers
are self-evident.

-- Chris