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  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:   Sun, 17 Sep 2017 10:47:16 -0700
From:   "Paul E. McKenney" <paulmck@...ux.vnet.ibm.com>
To:     Randy Dunlap <rdunlap@...radead.org>
Cc:     LKML <linux-kernel@...r.kernel.org>,
        "linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>,
        Jonathan Corbet <corbet@....net>
Subject: Re: rcu kernel-doc issues (4.14-rc1)

On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> > On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
> > 
> > .. kernel-doc:: include/linux/rcupdate.h
> >    :external:
> > ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
> > unknown option: "external".
> 
> $ grep external include/linux/rcupdate.h
>  * by a single external-to-structure RCU-protected pointer, then you may
>  * external-to-structure pointer -after- you have completely initialized
> 
> Do these comments somehow qualify as an "external" option?  If so, how
> do I tell kernel-doc to ignore them?  Or must I reword them to avoid
> the word "external"?
> 
> > .. kernel-doc:: include/linux/rcupdate_wait.h
> >    :external:
> > ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive:
> > unknown option: "external".
> 
> $ grep external include/linux/rcupdate_wait.h
> 
> There is no occurrence of the string "external" in this file.  So this
> "external" option is unknown to me as well.  So, any hints on how I
> should interpret these error messages?

And thanks to Akira Yokosawa for pointing out my confusion in reading
these error messages.  The line numbers of course apply to the file
Documentation/core-api/kernel-api.rst rather than the various RCU
C-language source files.

The patch below removes the error messages for me.  Is this what you
had in mind?  (Might need other options at some point, but somewhere
to start.)

							Thanx, Paul

------------------------------------------------------------------------

diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 8282099e0cbf..30b2666bf494 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -352,44 +352,44 @@ Read-Copy Update (RCU)
 ----------------------
 
 .. kernel-doc:: include/linux/rcupdate.h
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/rcupdate_wait.h
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/rcutree.h
-   :external:
+   :export
 
 .. kernel-doc:: kernel/rcu/tree.c
-   :external:
+   :export
 
 .. kernel-doc:: kernel/rcu/tree_plugin.h
-   :external:
+   :export
 
 .. kernel-doc:: kernel/rcu/tree_exp.h
-   :external:
+   :export
 
 .. kernel-doc:: kernel/rcu/update.c
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/srcu.h
-   :external:
+   :export
 
 .. kernel-doc:: kernel/rcu/srcutree.c
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/rculist_bl.h
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/rculist.h
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/rculist_nulls.h
-   :external:
+   :export
 
 .. kernel-doc:: include/linux/rcu_sync.h
-   :external:
+   :export
 
 .. kernel-doc:: kernel/rcu/sync.c
-   :external:
+   :export
 

Powered by blists - more mailing lists