linux.git/Documentation/process/deprecated.rst, branch v6.0

overflow: Implement size_t saturating arithmetic helpers

2022-02-16T22:29:48+00:00

In order to perform more open-coded replacements of common allocation
size arithmetic, the kernel needs saturating (SIZE_MAX) helpers for
multiplication, addition, and subtraction. For example, it is common in
allocators, especially on realloc, to add to an existing size:

    p = krealloc(map->patch,
                 sizeof(struct reg_sequence) * (map->patch_regs + num_regs),
                 GFP_KERNEL);

There is no existing saturating replacement for this calculation, and
just leaving the addition open coded inside array_size() could
potentially overflow as well. For example, an overflow in an expression
for a size_t argument might wrap to zero:

    array_size(anything, something_at_size_max + 1) == 0

Introduce size_mul(), size_add(), and size_sub() helpers that
implicitly promote arguments to size_t and saturated calculations for
use in allocations. With these helpers it is also possible to redefine
array_size(), array3_size(), flex_array_size(), and struct_size() in
terms of the new helpers.

As with the check_*_overflow() helpers, the new helpers use __must_check,
though what is really desired is a way to make sure that assignment is
only to a size_t lvalue. Without this, it's still possible to introduce
overflow/underflow via type conversion (i.e. from size_t to int).
Enforcing this will currently need to be left to static analysis or
future use of -Wconversion.

Additionally update the overflow unit tests to force runtime evaluation
for the pathological cases.

Cc: Rasmus Villemoes 
Cc: Gustavo A. R. Silva 
Cc: Nathan Chancellor 
Cc: Jason Gunthorpe 
Cc: Nick Desaulniers 
Cc: Leon Romanovsky 
Cc: Keith Busch 
Cc: Len Baker 
Signed-off-by: Kees Cook

docs: deprecated.rst: Clarify open-coded arithmetic with literals

2021-10-26T15:43:54+00:00

Although using literals for size calculation in allocator arguments may
be harmless due to compiler warnings in case of overflows, it is better
to refactor the code to avoid the use of open-coded arithmetic.

So, clarify the preferred way in these cases.

Suggested-by: Kees Cook 
Signed-off-by: Len Baker 
Reviewed-by: Gustavo A. R. Silva 
Link: https://lore.kernel.org/r/20210925143455.21221-1-len.baker@gmx.com
Signed-off-by: Jonathan Corbet

deprecated.rst: Include details on "no_hash_pointers"

2021-07-25T20:30:55+00:00

Linus decided a debug toggle for %p was tolerable, so update the
%p deprecation documentation.

Signed-off-by: Kees Cook 
Link: https://lore.kernel.org/r/20210723200526.3424128-1-keescook@chromium.org
Signed-off-by: Jonathan Corbet

docs: deprecated.rst: Expand str*cpy() replacement notes

2020-10-21T21:09:16+00:00

The notes on replacing the deprecated str*cpy() functions didn't call
enough attention to the change in return type. Add these details and
clean up the language a bit more.

Signed-off-by: Kees Cook 
Acked-by: Gustavo A. R. Silva 
Link: https://lore.kernel.org/r/20201015231730.2138505-1-keescook@chromium.org
Signed-off-by: Jonathan Corbet

docs: deprecated.rst: Update zero-length/one-element arrays section

2020-09-09T17:37:49+00:00

Update information in the zero-length and one-element arrays section
and illustrate how to make use of the new flex_array_size() helper,
together with struct_size() and a flexible-array member.

Signed-off-by: Gustavo A. R. Silva 
Acked-by: Kees Cook 
Link: https://lore.kernel.org/r/20200901010949.GA21398@embeddedor
Signed-off-by: Jonathan Corbet

deprecated.rst: Remove now removed uninitialized_var

2020-08-31T22:31:15+00:00

It's now gone from the kernel so remove it from the deprecated API text.

Signed-off-by: Joe Perches 
Reviewed-by: Nick Desaulniers 
Link: https://lore.kernel.org/r/5e10c1645dd8f735215cf54a74db0f8dd3f6cbd5.camel@perches.com
Signed-off-by: Jonathan Corbet

docs: Fix function name trailing double-()s

2020-08-24T23:19:07+00:00

I noticed a double-() in the deprecated.rst rendering today. Fix that
one and two others in the Documentation/ tree.

Acked-by: "Paul E. McKenney"  # For RCU
Signed-off-by: Kees Cook 
Link: https://lore.kernel.org/r/20200817233207.4083538-1-keescook@chromium.org
Signed-off-by: Jonathan Corbet

Merge tag 'docs-5.9' of git://git.lwn.net/linux

2020-08-05T05:47:54+00:00

Pull documentation updates from Jonathan Corbet:
 "It's been a busy cycle for documentation - hopefully the busiest for a
  while to come. Changes include:

   - Some new Chinese translations

   - Progress on the battle against double words words and non-HTTPS
     URLs

   - Some block-mq documentation

   - More RST conversions from Mauro. At this point, that task is
     essentially complete, so we shouldn't see this kind of churn again
     for a while. Unless we decide to switch to asciidoc or
     something...:)

   - Lots of typo fixes, warning fixes, and more"

* tag 'docs-5.9' of git://git.lwn.net/linux: (195 commits)
  scripts/kernel-doc: optionally treat warnings as errors
  docs: ia64: correct typo
  mailmap: add entry for 
  doc/zh_CN: add cpu-load Chinese version
  Documentation/admin-guide: tainted-kernels: fix spelling mistake
  MAINTAINERS: adjust kprobes.rst entry to new location
  devices.txt: document rfkill allocation
  PCI: correct flag name
  docs: filesystems: vfs: correct flag name
  docs: filesystems: vfs: correct sync_mode flag names
  docs: path-lookup: markup fixes for emphasis
  docs: path-lookup: more markup fixes
  docs: path-lookup: fix HTML entity mojibake
  CREDITS: Replace HTTP links with HTTPS ones
  docs: process: Add an example for creating a fixes tag
  doc/zh_CN: add Chinese translation prefer section
  doc/zh_CN: add clearing-warn-once Chinese version
  doc/zh_CN: add admin-guide index
  doc:it_IT: process: coding-style.rst: Correct __maybe_unused compiler label
  futex: MAINTAINERS: Re-add selftests directory
  ...

docs: deprecated.rst: Add uninitialized_var()

2020-07-16T19:32:24+00:00

Nothing should be using this macro, and the entire idea of tricking the
compiler into silencing such warnings is a mistake.

Cc: Jonathan Corbet 
Cc: "Gustavo A. R. Silva" 
Cc: Joe Perches 
Cc: linux-doc@vger.kernel.org
Reviewed-by: Nick Desaulniers 
Signed-off-by: Kees Cook

docs: deprecated.rst: Add zero-length and one-element arrays

2020-06-19T19:39:01+00:00

Add zero-length and one-element arrays to the list.

While I continue replacing zero-length and one-element arrays with
flexible-array members, I need a reference to point people to, so
they don't introduce more instances of such arrays. And while here,
add a note to the "open-coded arithmetic in allocator arguments"
section, on the use of struct_size() and the arrays-to-deprecate
mentioned here.

Co-developed-by: Kees Cook 
Signed-off-by: Kees Cook 
Signed-off-by: Gustavo A. R. Silva 
Acked-by: Kees Cook 
Link: https://lore.kernel.org/r/20200608213711.GA22271@embeddedor
Signed-off-by: Jonathan Corbet