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

Shuah Khan
2020-10-15T01:20:20Z

On 10/13/20 5:27 AM, Mauro Carvalho Chehab wrote:
> Em Fri, 9 Oct 2020 09:55:56 -0600
> Shuah Khan <skhan@linuxfoundation.org> 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@linuxfoundation.org>
>> Signed-off-by: Shuah Khan <skhan@linuxfoundation.org>
>
> 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