Re: [PATCH v3 01/11] counters: Introduce counter_atomic* counters

[Shuah Khan]

On 10/13/20 5:27 AM, Mauro Carvalho Chehab wrote:
> Em Fri,  9 Oct 2020 09:55:56 -0600
> Shuah Khan <skhan@xxxxxxxxxxxxxxxxxxx> escreveu:
>
> > Introduce Simple atomic counters.
> >
> > There are a number of atomic_t usages in the kernel where atomic_t api
> > is used strictly for counting and not for managing object lifetime. In
> > some cases, atomic_t might not even be needed.
> >
> > The purpose of these counters is to clearly differentiate atomic_t
> > counters from atomic_t usages that guard object lifetimes, hence prone
> > to overflow and underflow errors. It allows tools that scan for underflow
> > and overflow on atomic_t usages to detect overflow and underflows to scan
> > just the cases that are prone to errors.
> >
> > Simple atomic counters api provides interfaces for simple atomic counters
> > that just count, and don't guard resource lifetimes. The interfaces are
> > built on top of atomic_t api, providing a smaller subset of atomic_t
> > interfaces necessary to support simple counters.
> >
> > Counter wraps around to INT_MIN when it overflows and should not be used
> > to guard resource lifetimes, device usage and open counts that control
> > state changes, and pm states. Overflowing to INT_MIN is consistent with
> > the atomic_t api, which it is built on top of.
> >
> > Using counter_atomic* to guard lifetimes could lead to use-after free
> > when it overflows and undefined behavior when used to manage state
> > changes and device usage/open states.
> >
> > Reviewed-by: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
> > Signed-off-by: Shuah Khan <skhan@xxxxxxxxxxxxxxxxxxx>
>
> Did you try building this with htmldocs? It produces 3 new warnings
> due to wrong usage of the "ref" tag:
>
> 	.../Documentation/core-api/counters.rst:46: WARNING: undefined label: test counters module (if the link has no caption the label must precede a section header)
> 	.../Documentation/core-api/counters.rst:49: WARNING: undefined label: selftest for counters (if the link has no caption the label must precede a section header)
> 	.../Documentation/core-api/counters.rst:62: WARNING: undefined label: atomic_ops (if the link has no caption the label must precede a section header)

I added the document to patch 1/11 and the referenced file gets added
in 2/11. Poor planning on my part.

I will fix it.

> (plus another one that I'll be sending a fixup patch anytime soon)

Thanks for the fix.

> Are those referring to some documents that don't exist yet uptream?
> Or are you trying to force Sphinx to generate a cross-reference for
> a C file at the tree? If it is the latter, then this won't work,
> as it will only generate cross-references for files that are placed
> inside the documentation output dir (Documentation/output, by default).

Th first two aren't in upstream. atomic_ops exists - I will double check
the link.

thanks,
-- Shuah