kernel/linux.git/Documentation/process/deprecated.rst, branch v7.0-rc7

slab: Introduce kmalloc_flex() and family

2026-01-14T22:43:01+00:00

As done for kmalloc_obj*(), introduce a type-aware allocator for flexible arrays, which may also have "counted_by" annotations: ptr = kmalloc(struct_size(ptr, flex_member, count), gfp); becomes: ptr = kmalloc_flex(*ptr, flex_member, count, gfp); The internal use of __flex_counter() allows for automatically setting the counter member of a struct's flexible array member when it has been annotated with __counted_by(), avoiding any missed early size initializations while __counted_by() annotations are added to the kernel. Additionally, this also checks for "too large" allocations based on the type size of the counter variable. For example: if (count > type_max(ptr->flex_counter)) fail...; size = struct_size(ptr, flex_member, count); ptr = kmalloc(size, gfp); if (!ptr) fail...; ptr->flex_counter = count; becomes (n.b. unchanged from earlier example): ptr = kmalloc_flex(*ptr, flex_member, count, gfp); if (!ptr) fail...; ptr->flex_counter = count; Note that manual initialization of the flexible array counter is still required (at some point) after allocation as not all compiler versions support the __counted_by annotation yet. But doing it internally makes sure they cannot be missed when __counted_by _is_ available, meaning that the bounds checker will not trip due to the lack of "early enough" initializations that used to work before enabling the stricter bounds checking. For example: ptr = kmalloc_flex(*ptr, flex_member, count, gfp); fill(ptr->flex, count); ptr->flex_count = count; This works correctly before adding a __counted_by annotation (since nothing is checking ptr->flex accesses against ptr->flex_count). After adding the annotation, the bounds sanitizer would trip during fill() because ptr->flex_count wasn't set yet. But with kmalloc_flex() setting ptr->flex_count internally at allocation time, the existing code works without needing to move the ptr->flex_count assignment before the call to fill(). (This has been a stumbling block for __counted_by adoption.) Link: https://patch.msgid.link/20251203233036.3212363-4-kees@kernel.org Acked-by: Vlastimil Babka Signed-off-by: Kees Cook

slab: Introduce kmalloc_obj() and family

2026-01-14T22:43:01+00:00

Introduce type-aware kmalloc-family helpers to replace the common idioms for single object and arrays of objects allocation: ptr = kmalloc(sizeof(*ptr), gfp); ptr = kmalloc(sizeof(struct some_obj_name), gfp); ptr = kzalloc(sizeof(*ptr), gfp); ptr = kmalloc_array(count, sizeof(*ptr), gfp); ptr = kcalloc(count, sizeof(*ptr), gfp); These become, respectively: ptr = kmalloc_obj(*ptr, gfp); ptr = kmalloc_obj(*ptr, gfp); ptr = kzalloc_obj(*ptr, gfp); ptr = kmalloc_objs(*ptr, count, gfp); ptr = kzalloc_objs(*ptr, count, gfp); Beyond the other benefits outlined below, the primary ergonomic benefit is the elimination of needing "sizeof" nor the type name, and the enforcement of assignment types (they do not return "void *", but rather a pointer to the type of the first argument). The type name _can_ be used, though, in the case where an assignment is indirect (e.g. via "return"). This additionally allows[1] variables to be declared via __auto_type: __auto_type ptr = kmalloc_obj(struct foo, gfp); Internal introspection of the allocated type now becomes possible, allowing for future alignment-aware choices to be made by the allocator and future hardening work that can be type sensitive. For example, adding __alignof(*ptr) as an argument to the internal allocators so that appropriate/efficient alignment choices can be made, or being able to correctly choose per-allocation offset randomization within a bucket that does not break alignment requirements. Link: https://lore.kernel.org/all/CAHk-=wiCOTW5UftUrAnvJkr6769D29tF7Of79gUjdQHS_TkF5A@mail.gmail.com/ [1] Acked-by: Vlastimil Babka Link: https://patch.msgid.link/20251203233036.3212363-1-kees@kernel.org Signed-off-by: Kees Cook

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