From patchwork Fri Sep 13 08:37:14 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Vlastimil Babka X-Patchwork-Id: 13803109 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 02DC3FA3730 for ; Fri, 13 Sep 2024 08:37:25 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 11F396B00C6; Fri, 13 Sep 2024 04:37:25 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 0D0236B00C7; Fri, 13 Sep 2024 04:37:25 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id E62B56B00C8; Fri, 13 Sep 2024 04:37:24 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0011.hostedemail.com [216.40.44.11]) by kanga.kvack.org (Postfix) with ESMTP id C42DD6B00C6 for ; Fri, 13 Sep 2024 04:37:24 -0400 (EDT) Received: from smtpin27.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay06.hostedemail.com (Postfix) with ESMTP id 78030AB6B7 for ; Fri, 13 Sep 2024 08:37:24 +0000 (UTC) X-FDA: 82559060808.27.1E60D06 Received: from smtp-out2.suse.de (smtp-out2.suse.de [195.135.223.131]) by imf14.hostedemail.com (Postfix) with ESMTP id 49EB310000A for ; Fri, 13 Sep 2024 08:37:21 +0000 (UTC) Authentication-Results: imf14.hostedemail.com; dkim=pass header.d=suse.cz header.s=susede2_rsa header.b=0AHeLgBE; dkim=pass header.d=suse.cz header.s=susede2_ed25519 header.b=101KSxgx; dkim=pass header.d=suse.cz header.s=susede2_rsa header.b=0AHeLgBE; dkim=pass header.d=suse.cz header.s=susede2_ed25519 header.b=101KSxgx; dmarc=none; spf=pass (imf14.hostedemail.com: domain of vbabka@suse.cz designates 195.135.223.131 as permitted sender) smtp.mailfrom=vbabka@suse.cz ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1726216523; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-transfer-encoding:content-transfer-encoding: in-reply-to:references:dkim-signature; bh=Q0hOo4JLaVM9mohU1sRIDwzdG/8iyOJYwrC92+YDxc8=; b=j4lSRWF4R8OKcsYoU3WI3Np1ec7N2JH8v3h6bPbed8d7krTw61xcBz3mCeHlbWpXPKORUU Jek26dYREnWZVbijid6wDtHk6N3yXbbr43MM//r9FQQBpAu+9mZZ9Ck9UgvIRMwkS8ag1v 8xyi9tHnMrpbRWDaFaaKuggv0Znliro= ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1726216523; a=rsa-sha256; cv=none; b=cpe4UV8ekInRNpJRsIEjHY+bZUYNkZZY8eKRf5vkRTcSBuCjxVkEqvxRNEol9rHvMo2D/g ofjUqIq0dtfRM1S4Uo3JbkzbUJ0bnVZXNPbyy/980Ad6LO9QV77KvftkdbzFG44LfMvgbo /10p2KOy99Gi7bi+AXvW5DSxwduIMLc= ARC-Authentication-Results: i=1; imf14.hostedemail.com; dkim=pass header.d=suse.cz header.s=susede2_rsa header.b=0AHeLgBE; dkim=pass header.d=suse.cz header.s=susede2_ed25519 header.b=101KSxgx; dkim=pass header.d=suse.cz header.s=susede2_rsa header.b=0AHeLgBE; dkim=pass header.d=suse.cz header.s=susede2_ed25519 header.b=101KSxgx; dmarc=none; spf=pass (imf14.hostedemail.com: domain of vbabka@suse.cz designates 195.135.223.131 as permitted sender) smtp.mailfrom=vbabka@suse.cz Received: from imap1.dmz-prg2.suse.org (imap1.dmz-prg2.suse.org [IPv6:2a07:de40:b281:104:10:150:64:97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by smtp-out2.suse.de (Postfix) with ESMTPS id 7A9C71F7C3; Fri, 13 Sep 2024 08:37:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1726216639; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version: content-transfer-encoding:content-transfer-encoding; bh=Q0hOo4JLaVM9mohU1sRIDwzdG/8iyOJYwrC92+YDxc8=; b=0AHeLgBEE0XoQu7zufKuWrGl/IXqSu3l6/jJ28O/9qTIJmdgRuE6rZcR5/N2p0QD/n1i6y OfBEw4l0FBzWlk3aSXJKWINY9qubfGJIHK8nAcKUnHj6bpCgF3oyY2CWFwssD3cu1DfeFv R6kt2t62jdiyEDITwkOXBV3UrkezegA= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1726216639; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version: content-transfer-encoding:content-transfer-encoding; bh=Q0hOo4JLaVM9mohU1sRIDwzdG/8iyOJYwrC92+YDxc8=; b=101KSxgxbFwyHOIImf7x4oAAEBmWdy575MQaWJcMNPs++zKY5Ylr2cjYGyf4JIOHftThg9 iVMWgxkdttKU+4AQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1726216639; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version: content-transfer-encoding:content-transfer-encoding; bh=Q0hOo4JLaVM9mohU1sRIDwzdG/8iyOJYwrC92+YDxc8=; b=0AHeLgBEE0XoQu7zufKuWrGl/IXqSu3l6/jJ28O/9qTIJmdgRuE6rZcR5/N2p0QD/n1i6y OfBEw4l0FBzWlk3aSXJKWINY9qubfGJIHK8nAcKUnHj6bpCgF3oyY2CWFwssD3cu1DfeFv R6kt2t62jdiyEDITwkOXBV3UrkezegA= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1726216639; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version: content-transfer-encoding:content-transfer-encoding; bh=Q0hOo4JLaVM9mohU1sRIDwzdG/8iyOJYwrC92+YDxc8=; b=101KSxgxbFwyHOIImf7x4oAAEBmWdy575MQaWJcMNPs++zKY5Ylr2cjYGyf4JIOHftThg9 iVMWgxkdttKU+4AQ== Received: from imap1.dmz-prg2.suse.org (localhost [127.0.0.1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by imap1.dmz-prg2.suse.org (Postfix) with ESMTPS id 57D8313999; Fri, 13 Sep 2024 08:37:19 +0000 (UTC) Received: from dovecot-director2.suse.de ([2a07:de40:b281:106:10:150:64:167]) by imap1.dmz-prg2.suse.org with ESMTPSA id SfoaFb/542bcQQAAD6G6ig (envelope-from ); Fri, 13 Sep 2024 08:37:19 +0000 From: Vlastimil Babka To: Christoph Lameter , David Rientjes , Christian Brauner Cc: Andrew Morton , Hyeonggon Yoo <42.hyeyoo@gmail.com>, Kees Cook , Roman Gushchin , Jann Horn , Mike Rapoport , linux-mm@kvack.org, Vlastimil Babka Subject: [PATCH] mm, slab: restore kerneldoc for kmem_cache_create() Date: Fri, 13 Sep 2024 10:37:14 +0200 Message-ID: <20240913083713.14838-2-vbabka@suse.cz> X-Mailer: git-send-email 2.46.0 MIME-Version: 1.0 X-Rspamd-Action: no action X-Rspamd-Server: rspam07 X-Rspamd-Queue-Id: 49EB310000A X-Stat-Signature: u6qi4o4foybmb59eqteebkj53ksfx135 X-Rspam-User: X-HE-Tag: 1726216641-986303 X-HE-Meta: U2FsdGVkX18BKpXeS922OF5zlCNWfMVbnxjepwQTbsymYI+fnNdIeacQhrYTcFuBGMPzlzgzevIFE07HZZPmRCA8d84bZpkMyS5SBbAcvzuHe5QJM+Y6I3bs2dyO6SHmLgLNFczTPIaSXMXmHYa1I61ksvMb1KbuXNQ1R4wxufuThizifsF0JJzkFGnQy93jESusFWpbgB2gE4NTK20/Pjt/N21undq/yLGbC/Mm+DfEeb18WQSMcbfL4YShX00ZL/ukudtQQA2jHdEyhhanm8Z/UH4F2y8sxrjLFTFLwp6Mmef49CKaInZXfcBvas8tRvd8J293cnbr9gBAzn9OzSF8cbNpX9DIyBQauatP6+yCmKeAPRqZpIKPXtudwv9XoE1wZIrF1wIq/o4w/2z0Ex4eVFgy246xrpCpPAQtoqZPpmPVBgpsWbAB+v8L88Ii1yeRlVjmt1tRSpnpR0QUiwdhWWDK5g4fa5IvRcS1NSqboA9zPYepZVlRrw7C/Ed7E3H88T4rRcX5Wuee7xHRwj1YwdBaLcayhHswFUqtD5r6uAVAVJLmdEyXzz+f67t0C+I2MwjAH8KqO6GJS8eKIZ1jTkFGD6XNW4D2YwvZdleQ8JimAFMNYkny8gJlyAd5yvdcrJLujbWEXFOfaGhx+NbsYJh7cwn6xuS7csqh6ZZb7d01xh17NYGrCVX5u3hCNlCXyqCq+0kzJzDOLkYS5c2wjCrzuSAYdGA77EaBxpWoa5AbIQy2WQZYRinnn1+gcb7Jiaqj98xaDfRupEBVnVNGBMrqNNTax8FKv+lbJUQ6B/B5NNMd6cgSHmBedtwbaNJodSeT3f1vVB4fNQYhc28lHPETy3HGTpvOFDodYrVIVwAWaQdSIK22LYFmTjtpt+jeOZ3RQU6zl/UDLKCW0UzlDgB3JL9I7W6ct9XWCSqd2HhynAbmkLg3cKLdrel8vKjpGx8htm411/gw/uU T3Q3dlzL cNcevV0PmG6eOpju8XTMSk/5OZeHSNFCehrmUPbC57uNFMNb8tebn00UbqiLTlDk0QDaOVLLKlkIjE/pidVVUhTtqKeU+KidHwDe8HLSZVyrcxY1PxsT1LcOBiKx3NNveuNcPbFpu/e7zTfboVh7wKDY0XBtFT9hvMNpE6Fic3+udulFfylSSS+pSA9U7PTkrTC/DFs63vqnhGU6MhJGfwVCzODvgkxjvif0TsW/ytO34vqU5IM5A7qeFfvFiTXPpfFKEZ0a8A4olKIaggEs9F/diV+styvOEl/gQXDhXmJ/8RsZo5zYhBVYJRCm9p0G6woAaVHua73IZu2BzQS8NmdD/gRaOz/cwXe5ZBVxa3yDF/Cw= X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: As kmem_cache_create() became a _Generic() wrapper macro, it currently has no kerneldoc despite being the main API to use. Add it. Also adjust kmem_cache_create_usercopy() kerneldoc to indicate it is now a legacy wrapper. Also expand the kerneldoc for struct kmem_cache_args, especially for the freeptr_offset field, where important details were removed with the removal of kmem_cache_create_rcu(). Signed-off-by: Vlastimil Babka Reviewed-by: Christian Brauner Acked-by: David Rientjes --- A late change, but only changes comments and it means we won't regress the kerneldocs due to the refactoring. Further improvements are possible (i.e. turning descriptions of the main SLAB_ flags to kerneldocs) but that can wait. include/linux/slab.h | 114 ++++++++++++++++++++++++++++++++++--------- mm/slab_common.c | 10 ++-- 2 files changed, 98 insertions(+), 26 deletions(-) diff --git a/include/linux/slab.h b/include/linux/slab.h index 331412a9f4f2..6a8ab7ef3af7 100644 --- a/include/linux/slab.h +++ b/include/linux/slab.h @@ -242,19 +242,72 @@ bool slab_is_available(void); /** * struct kmem_cache_args - Less common arguments for kmem_cache_create() - * @align: The required alignment for the objects. - * @useroffset: Usercopy region offset - * @usersize: Usercopy region size - * @freeptr_offset: Custom offset for the free pointer in RCU caches - * @use_freeptr_offset: Whether a @freeptr_offset is used - * @ctor: A constructor for the objects. + * + * Any uninitialized fields of the structure are interpreted as unused. The + * exception is @freeptr_offset where %0 is a valid value, so + * @use_freeptr_offset must be also set to %true in order to interpret the field + * as used. For @useroffset %0 is also valid, but only with non-%0 + * @usersize. + * + * When %NULL args is passed to kmem_cache_create(), it is equivalent to all + * fields unused. */ struct kmem_cache_args { + /** + * @align: The required alignment for the objects. + * + * %0 means no specific alignment is requested. + */ unsigned int align; + /** + * @useroffset: Usercopy region offset. + * + * %0 is a valid offset, when @usersize is non-%0 + */ unsigned int useroffset; + /** + * @usersize: Usercopy region size. + * + * %0 means no usercopy region is specified. + */ unsigned int usersize; + /** + * @freeptr_offset: Custom offset for the free pointer + * in &SLAB_TYPESAFE_BY_RCU caches + * + * By default &SLAB_TYPESAFE_BY_RCU caches place the free pointer + * outside of the object. This might cause the object to grow in size. + * Cache creators that have a reason to avoid this can specify a custom + * free pointer offset in their struct where the free pointer will be + * placed. + * + * Note that placing the free pointer inside the object requires the + * caller to ensure that no fields are invalidated that are required to + * guard against object recycling (See &SLAB_TYPESAFE_BY_RCU for + * details). + * + * Using %0 as a value for @freeptr_offset is valid. If @freeptr_offset + * is specified, %use_freeptr_offset must be set %true. + * + * Note that @ctor currently isn't supported with custom free pointers + * as a @ctor requires an external free pointer. + */ unsigned int freeptr_offset; + /** + * @use_freeptr_offset: Whether a @freeptr_offset is used. + */ bool use_freeptr_offset; + /** + * @ctor: A constructor for the objects. + * + * The constructor is invoked for each object in a newly allocated slab + * page. It is the cache user's responsibility to free object in the + * same state as after calling the constructor, or deal appropriately + * with any differences between a freshly constructed and a reallocated + * object. + * + * %NULL means no constructor. + */ void (*ctor)(void *); }; @@ -275,30 +328,20 @@ __kmem_cache_create(const char *name, unsigned int size, unsigned int align, } /** - * kmem_cache_create_usercopy - Create a cache with a region suitable - * for copying to userspace + * kmem_cache_create_usercopy - Create a kmem cache with a region suitable + * for copying to userspace. * @name: A string which is used in /proc/slabinfo to identify this cache. * @size: The size of objects to be created in this cache. * @align: The required alignment for the objects. * @flags: SLAB flags * @useroffset: Usercopy region offset * @usersize: Usercopy region size - * @ctor: A constructor for the objects. - * - * Cannot be called within a interrupt, but can be interrupted. - * The @ctor is run when new pages are allocated by the cache. - * - * The flags are + * @ctor: A constructor for the objects, or %NULL. * - * %SLAB_POISON - Poison the slab with a known test pattern (a5a5a5a5) - * to catch references to uninitialised memory. - * - * %SLAB_RED_ZONE - Insert `Red` zones around the allocated memory to check - * for buffer overruns. - * - * %SLAB_HWCACHE_ALIGN - Align the objects in this cache to a hardware - * cacheline. This can be beneficial if you're counting cycles as closely - * as davem. + * This is a legacy wrapper, new code should use either KMEM_CACHE_USERCOPY() + * if whitelisting a single field is sufficient, or kmem_cache_create() with + * the necessary parameters passed via the args parameter (see + * &struct kmem_cache_args) * * Return: a pointer to the cache on success, NULL on failure. */ @@ -333,6 +376,31 @@ __kmem_cache_default_args(const char *name, unsigned int size, return __kmem_cache_create_args(name, size, &kmem_default_args, flags); } +/** + * kmem_cache_create - Create a kmem cache. + * @__name: A string which is used in /proc/slabinfo to identify this cache. + * @__object_size: The size of objects to be created in this cache. + * @__args: Optional arguments, see &struct kmem_cache_args. Passing %NULL + * means defaults will be used for all the arguments. + * + * This is currently implemented as a macro using ``_Generic()`` to call + * either the new variant of the function, or a legacy one. + * + * The new variant has 4 parameters: + * ``kmem_cache_create(name, object_size, args, flags)`` + * + * See __kmem_cache_create_args() which implements this. + * + * The legacy variant has 5 parameters: + * ``kmem_cache_create(name, object_size, align, flags, ctor)`` + * + * The align and ctor parameters map to the respective fields of + * &struct kmem_cache_args + * + * Context: Cannot be called within a interrupt, but can be interrupted. + * + * Return: a pointer to the cache on success, NULL on failure. + */ #define kmem_cache_create(__name, __object_size, __args, ...) \ _Generic((__args), \ struct kmem_cache_args *: __kmem_cache_create_args, \ diff --git a/mm/slab_common.c b/mm/slab_common.c index 30000dcf0736..86c2e6f4a1ce 100644 --- a/mm/slab_common.c +++ b/mm/slab_common.c @@ -239,13 +239,17 @@ static struct kmem_cache *create_cache(const char *name, } /** - * __kmem_cache_create_args - Create a kmem cache + * __kmem_cache_create_args - Create a kmem cache. * @name: A string which is used in /proc/slabinfo to identify this cache. * @object_size: The size of objects to be created in this cache. - * @args: Arguments for the cache creation (see struct kmem_cache_args). + * @args: Additional arguments for the cache creation (see + * &struct kmem_cache_args). * @flags: See %SLAB_* flags for an explanation of individual @flags. * - * Cannot be called within a interrupt, but can be interrupted. + * Not to be called directly, use the kmem_cache_create() wrapper with the same + * parameters. + * + * Context: Cannot be called within a interrupt, but can be interrupted. * * Return: a pointer to the cache on success, NULL on failure. */