[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-Id: <20181107195743.GA4170@linux.ibm.com>
Date: Wed, 7 Nov 2018 11:57:43 -0800
From: "Paul E. McKenney" <paulmck@...ux.ibm.com>
To: Thomas Gleixner <tglx@...utronix.de>
Cc: LKML <linux-kernel@...r.kernel.org>, x86@...nel.org,
Peter Zijlstra <peterz@...radead.org>,
John Stultz <john.stultz@...aro.org>,
Arnaldo Carvalho de Melo <acme@...hat.com>,
Frederic Weisbecker <frederic@...nel.org>,
Jonathan Corbet <corbet@....net>,
Andy Lutomirski <luto@...nel.org>,
Marc Zyngier <marc.zyngier@....com>,
Daniel Lezcano <daniel.lezcano@...aro.org>,
Dave Hansen <dave.hansen@...ux.intel.com>,
Ard Biesheuvel <ard.biesheuvel@...aro.org>,
Will Deacon <will.deacon@....com>,
Mark Brown <broonie@...nel.org>,
Dan Williams <dan.j.williams@...el.com>
Subject: Re: [patch 2/2] Documentation/process: Add tip tree handbook
On Wed, Nov 07, 2018 at 06:44:07PM +0100, Thomas Gleixner wrote:
> On Wed, 7 Nov 2018, Thomas Gleixner wrote:
>
> > Add a document to the subsystem/maintainer handbook section, which explains
> > what the tip tree is, how it operates and what rules and expectations it
> > has.
>
> Peter asked me to add a section about locking comments. I added it and
> forgot to refresh the patch before sending. Delta patch below.
>
> Thanks,
>
> tglx
> ---
> --- a/Documentation/process/maintainer-tip.rst
> +++ b/Documentation/process/maintainer-tip.rst
> @@ -578,6 +578,29 @@ Sentences in comments start with a upper
> usage of descriptive function names often replaces these tiny comments.
> Apply common sense as always.
>
> +
> +Documenting locking requirements
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> + Documenting locking requirements is a good thing, but comments are not
> + necessarily the best choice. Instead of writing::
> +
> + /* Caller must hold foo->lock */
> + void func(struct foo *foo)
> + {
> + ...
> + }
> +
> + Please use::
> +
> + void func(struct foo *foo)
> + {
> + lockdep_assert_held(&foo->lock);
> + ...
> + }
> +
> + The latter enables run time debugging when lockdep is enabled which
> + verifies that all callers hold the lock. Comments can't do that.
In PROVE_LOCKING kernels, lockdep_assert_held() emits a warning
if the caller doesn't hold the lock. Comments can't do that.
Thanx, Paul
Powered by blists - more mailing lists