kernel/linux.git/Documentation/process/deprecated.rst, branch v6.18.21

docs: deprecated.rst: Update an example

2023-07-14T19:36:31+00:00

vmalloc() has a 2-factor form. It is vmalloc_array(). So use another function as an example. Signed-off-by: Christophe JAILLET Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/3484e46180dd2cf05d993ff1a78b481bc2ad1f71.1687723931.git.christophe.jaillet@wanadoo.fr

docs: deprecated.rst: Add note about DECLARE_FLEX_ARRAY() usage

2023-01-13T16:26:19+00:00

There wasn't any mention of when/where DECLARE_FLEX_ARRAY() should be used, so add the rationale and an example to the deprecation docs. Suggested-by: Vincent Mailhol Cc: "Gustavo A. R. Silva" Signed-off-by: Kees Cook Link: https://lore.kernel.org/r/20230106200600.never.735-kees@kernel.org [jc: minor wording tweaks] Signed-off-by: Jonathan Corbet

string: Introduce strtomem() and strtomem_pad()

2022-09-07T23:37:26+00:00

One of the "legitimate" uses of strncpy() is copying a NUL-terminated string into a fixed-size non-NUL-terminated character array. To avoid the weaknesses and ambiguity of intent when using strncpy(), provide replacement functions that explicitly distinguish between trailing padding and not, and require the destination buffer size be discoverable by the compiler. For example: struct obj { int foo; char small[4] __nonstring; char big[8] __nonstring; int bar; }; struct obj p; /* This will truncate to 4 chars with no trailing NUL */ strncpy(p.small, "hello", sizeof(p.small)); /* p.small contains 'h', 'e', 'l', 'l' */ /* This will NUL pad to 8 chars. */ strncpy(p.big, "hello", sizeof(p.big)); /* p.big contains 'h', 'e', 'l', 'l', 'o', '\0', '\0', '\0' */ When the "__nonstring" attributes are missing, the intent of the programmer becomes ambiguous for whether the lack of a trailing NUL in the p.small copy is a bug. Additionally, it's not clear whether the trailing padding in the p.big copy is _needed_. Both cases become unambiguous with: strtomem(p.small, "hello"); strtomem_pad(p.big, "hello", 0); See also https://github.com/KSPP/linux/issues/90 Expand the memcpy KUnit tests to include these functions. Cc: Wolfram Sang Cc: Nick Desaulniers Cc: Geert Uytterhoeven Cc: Guenter Roeck Signed-off-by: Kees Cook

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