Re: [PATCH] documentation: Add disclaimer

From: Paul E. McKenney
Date: Thu Apr 14 2016 - 17:40:10 EST


On Wed, Jan 27, 2016 at 09:35:46AM +0100, Peter Zijlstra wrote:
> On Tue, Jan 26, 2016 at 12:11:43PM -0800, Paul E. McKenney wrote:
> > So Peter, would you like to update your patch to include yourself
> > and Will as authors?
>
> Sure, here goes.
>
> ---
> Subject: documentation: Add disclaimer
>
> It appears people are reading this document as a requirements list for
> building hardware. This is not the intent of this document. Nor is it
> particularly suited for this purpose.
>
> The primary purpose of this document is our collective attempt to define
> a set of primitives that (hopefully) allow us to write correct code on
> the myriad of SMP platforms Linux supports.
>
> Its a definite work in progress as our understanding of these platforms,
> and memory ordering in general, progresses.
>
> Nor does being mentioned in this document mean we think its a
> particularly good idea; the data dependency barrier required by Alpha
> being a prime example. Yes we have it, no you're insane to require it
> when building new hardware.
>
> Signed-off-by: Peter Zijlstra (Intel) <peterz@xxxxxxxxxxxxx>

Rather belatedly queued and pushed to -rcu, apologies for the delay.
One minor edit noted below.

Thanx, Paul

> ---
> Documentation/memory-barriers.txt | 18 +++++++++++++++++-
> 1 file changed, 17 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
> index a61be39c7b51..98626125f484 100644
> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -4,8 +4,24 @@
>
> By: David Howells <dhowells@xxxxxxxxxx>
> Paul E. McKenney <paulmck@xxxxxxxxxxxxxxxxxx>
> + Will Deacon <will.deacon@xxxxxxx>
> + Peter Zijlstra <peterz@xxxxxxxxxxxxx>
>
> -Contents:
> +==========
> +DISCLAIMER
> +==========
> +
> +This document is not a specification; it is intentionally (for the sake of
> +brevity) and unintentionally (due to being human) incomplete. This document is
> +meant as a guide to using the various memory barriers provided by Linux, but
> +in case of any doubt (and there are many) please ask.
> +
> +I repeat, this document is not a specification of what Linux expects from

s/I/To/ because there is more than one author.

> +hardware.
> +
> +========
> +CONTENTS
> +========
>
> (*) Abstract memory access model.
>
>