From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <tglx@linutronix.de>
X-Google-Smtp-Source: AH8x224C8Lh0jlMV0Tfm5asoKFSeHp/301T2PYIXq0BzjHBF+G7iMiLSvRzBfu33/czpTexbfx5+
ARC-Seal: i=1; a=rsa-sha256; t=1517139425; cv=none;
        d=google.com; s=arc-20160816;
        b=oWv6HvOfqwOeOi5LhC+5P5rEH2rAAK1Z9VtGSUS45g5ULXdbimPsxtEGOybJZw0TPx
         X6JaBkp4XKBp5p0FWRibRgjhVR10QmQZLdB41AB4SM9C3e7YfFSs4V2Y0tHIT+HTEm3D
         FeQuIGSYmOAmfCd+o0iGpci8eMPWasNBAN9x8Ki8YFoGeHN1ZHClkpZ2eZ8c19a15zQJ
         3JWdVlc0kIV/i234Shv5arqihE/nq20w0sQGBSyolVdEJ/Mne5NIkXc2I0NgXFAw18Wv
         w2vS2Y1uVG7Aywv+x5uTNWXs4H53oxP3xKggvwIZ0ka7Pn8I/DwC39JcdTU9IAijT9nO
         D+Pg==
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816;
        h=mime-version:user-agent:references:message-id:in-reply-to:subject
         :cc:to:from:date:arc-authentication-results;
        bh=a2ms7YtJfuT/bALbzRG5h96TzWU+K+r4HWueg4tTWIU=;
        b=Mt600mWCYfL7PTHXI7wUhH621/N+zH6k0WpgJ5o8pmMLg24T/CGobdWsvjo7N02Hxe
         00ImV/gLOxFIStbGxlDV4M0kT985K+3bPluix40YVAj6e91mQDOd8QYZ3Z5M7cLo7pEx
         8aNRe81R5frgFFoQ+JEbdJdPeAStC9sPdkltzNJ+ipy2ydcKv8GuJndUYdy2ukw2MEGr
         jCnefmED/qsToIKsbGsIqIBHtx3NdXS9wCCf1/XggSQ0P5s+8F4Ky7R4+kyASeMIG0nH
         tVI/0EOuHSneiHC3h/E/PF/9YNfb/ZCupahnkkeTrvdu8AVYQCVZkIPKOtUJFj1voiEI
         YGcw==
ARC-Authentication-Results: i=1; mx.google.com;
       spf=pass (google.com: best guess record for domain of tglx@linutronix.de designates 2a01:7a0:2:106d:700::1 as permitted sender) smtp.mailfrom=tglx@linutronix.de
Authentication-Results: mx.google.com;
       spf=pass (google.com: best guess record for domain of tglx@linutronix.de designates 2a01:7a0:2:106d:700::1 as permitted sender) smtp.mailfrom=tglx@linutronix.de
Date: Sun, 28 Jan 2018 12:36:33 +0100 (CET)
From: Thomas Gleixner <tglx@linutronix.de>
To: Ingo Molnar <mingo@kernel.org>
cc: Dan Williams <dan.j.williams@intel.com>, linux-arch@vger.kernel.org,
    Cyril Novikov <cnovikov@lynx.com>, kernel-hardening@lists.openwall.com,
    Peter Zijlstra <peterz@infradead.org>,
    Catalin Marinas <catalin.marinas@arm.com>, x86@kernel.org,
    Will Deacon <will.deacon@arm.com>, Russell King <linux@armlinux.org.uk>,
    Ingo Molnar <mingo@redhat.com>, gregkh@linuxfoundation.org,
    "H. Peter Anvin" <hpa@zytor.com>, torvalds@linux-foundation.org,
    alan@linux.intel.com, linux-kernel@vger.kernel.org
Subject: Re: [PATCH v5 02/12] array_idx: sanitize speculative array
 de-references
In-Reply-To: <20180128085500.djlm5rlbhjlpfj4i@gmail.com>
Message-ID: <alpine.DEB.2.20.1801281232130.2126@nanos>
References: <151703971300.26578.1185595719337719486.stgit@dwillia2-desk3.amr.corp.intel.com> <151703972396.26578.7326612698912543866.stgit@dwillia2-desk3.amr.corp.intel.com> <20180128085500.djlm5rlbhjlpfj4i@gmail.com>
User-Agent: Alpine 2.20 (DEB 67 2015-01-07)
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
X-Linutronix-Spam-Score: -1.0
X-Linutronix-Spam-Level: -
X-Linutronix-Spam-Status: No , -1.0 points, 5.0 required,  ALL_TRUSTED=-1,SHORTCIRCUIT=-0.0001
X-getmail-retrieved-from-mailbox: INBOX
X-GMAIL-THRID: =?utf-8?q?1590732017653801778?=
X-GMAIL-MSGID: =?utf-8?q?1590835990103806000?=
X-Mailing-List: linux-kernel@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>

On Sun, 28 Jan 2018, Ingo Molnar wrote:
> * Dan Williams <dan.j.williams@intel.com> wrote:
> > +
> > +#ifndef __NOSPEC_H__
> > +#define __NOSPEC_H__

_LINUX_NOSPEC_H

We have an established practice for those header guards...

> > +/*
> > + * When idx is out of bounds (idx >= sz), the sign bit will be set.
> > + * Extend the sign bit to all bits and invert, giving a result of zero
> > + * for an out of bounds idx, or ~0UL if within bounds [0, sz).
> > + */
> > +#ifndef array_idx_mask
> > +static inline unsigned long array_idx_mask(unsigned long idx, unsigned long sz)
> > +{
> > +	/*
> > +	 * Warn developers about inappropriate array_idx usage.
> > +	 *
> > +	 * Even if the cpu speculates past the WARN_ONCE branch, the
> 
> s/cpu/CPU
> 
> > +	 * sign bit of idx is taken into account when generating the
> > +	 * mask.
> > +	 *
> > +	 * This warning is compiled out when the compiler can infer that
> > +	 * idx and sz are less than LONG_MAX.
> 
> Please use 'idx' and 'sz' in quotes, to make sure they stand out more in free 
> flowing comment text. Also please use '()' to denote functions/methods.
> 
> I.e. something like:
> 
> 	 * Warn developers about inappropriate array_idx() usage.
> 	 *
> 	 * Even if the CPU speculates past the WARN_ONCE() branch, the
> 	 * sign bit of 'idx' is taken into account when generating the
> 	 * mask.
> 	 *
> 	 * This warning is compiled out when the compiler can infer that
> 	 * 'idx' and 'sz' are less than LONG_MAX.

I rather prefer to have a proper kernel doc instead of the comment above
the function and then use @idx and @sz in the code comments.

Thanks,

	tglx