Re: [PATCH 4/5] slab: Set freed variables to NULL by default
From: Matthew Wilcox
Date: Thu Mar 27 2025 - 15:48:16 EST
On Fri, Mar 21, 2025 at 01:41:00PM -0700, Kees Cook wrote:
> /**
> - * kfree - free previously allocated memory
> + * __kfree - free previously allocated memory
No. After applying this patch, we now have documentation for __kfree --
a function we want precisely 0 people to call directly, and no
documentation for kfree(), which is the function we want everybody to
use.
I don't know what the right solution to kernel documentation is here,
but this is definitely not it. Something I've done in the past is to
note that kernel-doc ignores preprocessor, so we could do something
like:
#if 0
/**
* kfree - blah blah
* @blah: blah
*
* blah blah blah
*/
void kfree(const void *object) { }
#endif
void __kfree(const void *object)
{
...
}
We'd get warnings if people asked the kbuild system to show them all
EXPORT_SYMBOL functions which don't have kdoc, but nobody's that
invested in having complete documentation. I don't know if this is
a good approach to solving the problem.