linux-kernel - Re: linux-next: build warnings after merge of the rcu tree

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]

Message-ID: <20201126151240.GP1437@paulmck-ThinkPad-P72>
Date:   Thu, 26 Nov 2020 07:12:40 -0800
From:   "Paul E. McKenney" <paulmck@...nel.org>
To:     Stephen Rothwell <sfr@...b.auug.org.au>
Cc:     "Uladzislau Rezki (Sony)" <urezki@...il.com>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
        Linux Next Mailing List <linux-next@...r.kernel.org>
Subject: Re: linux-next: build warnings after merge of the rcu tree

On Thu, Nov 26, 2020 at 05:44:28PM +1100, Stephen Rothwell wrote:
> Hi all,
> 
> After merging the rcu tree, today's linux-next build (htmldocs) produced
> these warnings:
> 
> include/linux/rcupdate.h:872: warning: Excess function parameter 'ptr' description in 'kfree_rcu'
> include/linux/rcupdate.h:872: warning: Excess function parameter 'rhf' description in 'kfree_rcu'
> 
> Introduced by commit
> 
>   beba8bdf2f16 ("rcu: Introduce kfree_rcu() single-argument macro")

Heh!  The documentation isn't dealing at all well with this situation.

Would one of the docbook experts have some advice, keeping in mind
that kfree_rcu might have either one or two arguments?

							Thanx, Paul

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

/**
 * kfree_rcu() - kfree an object after a grace period.
 * @ptr: pointer to kfree for both single- and double-argument invocations.
 * @rhf: the name of the struct rcu_head within the type of @ptr,
 *       but only for double-argument invocations.
 *
 * Many rcu callbacks functions just call kfree() on the base structure.
 * These functions are trivial, but their size adds up, and furthermore
 * when they are used in a kernel module, that module must invoke the
 * high-latency rcu_barrier() function at module-unload time.
 *
 * The kfree_rcu() function handles this issue.  Rather than encoding a
 * function address in the embedded rcu_head structure, kfree_rcu() instead
 * encodes the offset of the rcu_head structure within the base structure.
 * Because the functions are not allowed in the low-order 4096 bytes of
 * kernel virtual memory, offsets up to 4095 bytes can be accommodated.
 * If the offset is larger than 4095 bytes, a compile-time error will
 * be generated in kvfree_rcu_arg_2(). If this error is triggered, you can
 * either fall back to use of call_rcu() or rearrange the structure to
 * position the rcu_head structure into the first 4096 bytes.
 *
 * Note that the allowable offset might decrease in the future, for example,
 * to allow something like kmem_cache_free_rcu().
 *
 * The BUILD_BUG_ON check must not involve any function calls, hence the
 * checks are done in macros here.
 */
#define kfree_rcu kvfree_rcu