linux-kernel - Re: [PATCH v3 49/56] refcount.h: fix a kernel-doc markup

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Mon, 26 Oct 2020 10:16:20 +0100
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     Peter Zijlstra <peterz@...radead.org>
Cc:     Jonathan Corbet <corbet@....net>,
        Kees Cook <keescook@...omium.org>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Ard Biesheuvel <ardb@...nel.org>,
        Ingo Molnar <mingo@...nel.org>, Jann Horn <jannh@...gle.com>,
        Will Deacon <will@...nel.org>, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v3 49/56] refcount.h: fix a kernel-doc markup

Em Mon, 26 Oct 2020 09:10:59 +0100
Peter Zijlstra <peterz@...radead.org> escreveu:

> On Sat, Oct 24, 2020 at 08:28:27AM +0200, Mauro Carvalho Chehab wrote:
> > If the intent is to document the struct and its internal fields,
> > this kernel-doc should work:
> > 
> > 	/**
> > 	 * struct refcount_struct - variant of atomic_t specialized for reference counts
> > 	 * @refs: atomic_t counter field
> > 	 *
> > 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> > 	 * there. This avoids wrapping the counter and causing 'spurious'
> > 	 * use-after-free bugs.
> > 	 */
> > 
> > Which produces this result:  
> 
> Who cares... :-(

Anyone that would need to use refcount_t, instead of atomic_t.

> 
> > If you want both, then you would either split struct and typedef, e. g.
> > with something like:
> > 
> > 	/**
> > 	 * struct refcount_struct - variant of atomic_t specialized for reference counts
> > 	 * @refs: atomic_t counter field
> > 	 *
> > 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> > 	 * there. This avoids wrapping the counter and causing 'spurious'
> > 	 * use-after-free bugs.
> > 	 */
> > 	struct refcount_struct {
> > 	        atomic_t refs;
> > 	};
> > 
> > 	/**
> > 	 * typedef refcount_t - variant of atomic_t specialized for reference counts
> > 	 * @refs: atomic_t counter field
> > 	 *
> > 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> > 	 * there. This avoids wrapping the counter and causing 'spurious'
> > 	 * use-after-free bugs.
> > 	 */
> > 	typedef struct refcount_struct refcount_t;
> > 
> > Or, you could add the member at the description field. E. g. something
> > like this:
> > 
> > 	/**
> > 	 * typedef refcount_t - variant of atomic_t specialized for reference counts
> > 	 *
> > 	 * The counter saturates at REFCOUNT_SATURATED and will not move once
> > 	 * there. This avoids wrapping the counter and causing 'spurious'
> > 	 * use-after-free bugs.
> > 	 *
> > 	 * Members:
> > 	 *   ``refs``
> > 	 *        atomic_t counter field
> > 	 */
> > 	typedef struct refcount_struct {
> > 	        atomic_t refs;
> > 	} refcount_t;
> > 
> > If you want to test it, you can run kernel-doc directly, to see how
> > it will parse it. For ReST output, that's the syntax:
> > 
> > 	./scripts/kernel-doc --sphinx-version 3 include/linux/refcount.h  
> 
> I'll just go ahead and remove the superfluous * from the comment... It's
> trivially clear what is meant. If the stupid tool can't deal with that,
> I don't care.

The tool is not that stupid. What's wrong here is that the markup is
asking kernel-doc to document the struct, instead documenting the typedef:

 	/**
 	 * struct refcount_t - variant of atomic_t specialized for reference counts
...

There is no such struct!

Just doing:

	s/struct/typedef/

will do what you intend to document.

Thanks,
Mauro

[PATCH] refcount.h: fix a kernel-doc markup

The kernel-doc markup is wrong: it is asking the tool to document
struct refcount_struct, instead of documenting typedef refcount_t.

Fix it.
    
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>

diff --git a/include/linux/refcount.h b/include/linux/refcount.h
index 0e3ee25eb156..f572c62261a8 100644
--- a/include/linux/refcount.h
+++ b/include/linux/refcount.h
@@ -101,7 +101,7 @@
 struct mutex;
 
 /**
- * struct refcount_t - variant of atomic_t specialized for reference counts
+ * typedef refcount_t - variant of atomic_t specialized for reference counts
  * @refs: atomic_t counter field
  *
  * The counter saturates at REFCOUNT_SATURATED and will not move once