From patchwork Wed Oct 9 14:29:37 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Vlastimil Babka X-Patchwork-Id: 13828506 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 B4AC7CEDD9E for ; Wed, 9 Oct 2024 14:29:44 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 4E41C6B00D3; Wed, 9 Oct 2024 10:29:44 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 46CC76B00D4; Wed, 9 Oct 2024 10:29:44 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 2BC3C6B00D5; Wed, 9 Oct 2024 10:29:44 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0015.hostedemail.com [216.40.44.15]) by kanga.kvack.org (Postfix) with ESMTP id 0268C6B00D3 for ; Wed, 9 Oct 2024 10:29:43 -0400 (EDT) Received: from smtpin11.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay07.hostedemail.com (Postfix) with ESMTP id 6D597161640 for ; Wed, 9 Oct 2024 14:29:41 +0000 (UTC) X-FDA: 82654297446.11.4DDFF62 Received: from smtp-out1.suse.de (smtp-out1.suse.de [195.135.223.130]) by imf17.hostedemail.com (Postfix) with ESMTP id 74E6D40011 for ; Wed, 9 Oct 2024 14:29:41 +0000 (UTC) Authentication-Results: imf17.hostedemail.com; dkim=pass header.d=suse.cz header.s=susede2_rsa header.b=cHQt3MCr; dkim=pass header.d=suse.cz header.s=susede2_ed25519 header.b=mNtyBiKM; dkim=pass header.d=suse.cz header.s=susede2_rsa header.b=cHQt3MCr; dkim=pass header.d=suse.cz header.s=susede2_ed25519 header.b=mNtyBiKM; dmarc=none; spf=pass (imf17.hostedemail.com: domain of vbabka@suse.cz designates 195.135.223.130 as permitted sender) smtp.mailfrom=vbabka@suse.cz ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1728484154; a=rsa-sha256; cv=none; b=kdx0YbmMNjVliaiecuJosVNVbhbPxqA8W42s8euOY4d9M3AyfHLC/UO5rfvfgMkFLOri0d avIn6SCDeZhuRgHMS4lBwdYVLRHYzMhPhHENuLXjhB9yTpI4vrpviWOz5bb8MIfpTw0NU0 +yrNw3GbV3mtpP12NA5inaiHJzt3L/E= ARC-Authentication-Results: i=1; imf17.hostedemail.com; dkim=pass header.d=suse.cz header.s=susede2_rsa header.b=cHQt3MCr; dkim=pass header.d=suse.cz header.s=susede2_ed25519 header.b=mNtyBiKM; dkim=pass header.d=suse.cz header.s=susede2_rsa header.b=cHQt3MCr; dkim=pass header.d=suse.cz header.s=susede2_ed25519 header.b=mNtyBiKM; dmarc=none; spf=pass (imf17.hostedemail.com: domain of vbabka@suse.cz designates 195.135.223.130 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=1728484154; 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=kEEVUu4TR/KxCJYKxSfEmcKvSVeKXTKNpUyftRsOkgM=; b=hzZYsQd3LnpCgKpSZcwAokXr8oykpFvLHebAp6o6SpIdszT0Mm01edPikXjgGbYH+mZImb me+imR3Hz4no8C3qa5ZOIzcJ38Ju+wSbNS6oKEeX9Rego6I56PxtJrQ/eVJtqHRj5on7G8 SZsrWSl8m0x9ehBOR0+I1y3KiUR9AAE= Received: from imap1.dmz-prg2.suse.org (unknown [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-out1.suse.de (Postfix) with ESMTPS id C830F21E81; Wed, 9 Oct 2024 14:29:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1728484179; 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=kEEVUu4TR/KxCJYKxSfEmcKvSVeKXTKNpUyftRsOkgM=; b=cHQt3MCrfDgen/Rd/IKzmkDBT89/V2SfGNZp8a2SWl/kRGyzxLQRwnWJnM4RkT3qTHH+81 auNWA6LHezg7LHplpCaQ4v2GQuW0OtwJlhcVfxWKy04s2GQ4HsHNH7+cDJs+4g9kH/0EJ6 20FBmFMofBScQSoQtBa4ggzeZKVfNn0= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1728484179; 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=kEEVUu4TR/KxCJYKxSfEmcKvSVeKXTKNpUyftRsOkgM=; b=mNtyBiKMMpnvNu4tLamDOR/hFoTiW4E0BSaRcMEX3w8Gj27k9dcacimzQRnTCvRExRB+K9 +v9bN6RUlXZlaFDw== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1728484179; 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=kEEVUu4TR/KxCJYKxSfEmcKvSVeKXTKNpUyftRsOkgM=; b=cHQt3MCrfDgen/Rd/IKzmkDBT89/V2SfGNZp8a2SWl/kRGyzxLQRwnWJnM4RkT3qTHH+81 auNWA6LHezg7LHplpCaQ4v2GQuW0OtwJlhcVfxWKy04s2GQ4HsHNH7+cDJs+4g9kH/0EJ6 20FBmFMofBScQSoQtBa4ggzeZKVfNn0= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1728484179; 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=kEEVUu4TR/KxCJYKxSfEmcKvSVeKXTKNpUyftRsOkgM=; b=mNtyBiKMMpnvNu4tLamDOR/hFoTiW4E0BSaRcMEX3w8Gj27k9dcacimzQRnTCvRExRB+K9 +v9bN6RUlXZlaFDw== 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 B3F20136BA; Wed, 9 Oct 2024 14:29:39 +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 2pKZK1OTBmdgRAAAD6G6ig (envelope-from ); Wed, 09 Oct 2024 14:29:39 +0000 From: Vlastimil Babka To: David Rientjes , Christoph Lameter Cc: Hyeonggon Yoo <42.hyeyoo@gmail.com>, Roman Gushchin , Andrew Morton , linux-mm@kvack.org, Jonathan Corbet , linux-doc@vger.kernel.org, Vlastimil Babka Subject: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags Date: Wed, 9 Oct 2024 16:29:37 +0200 Message-ID: <20241009142936.56092-2-vbabka@suse.cz> X-Mailer: git-send-email 2.46.1 MIME-Version: 1.0 X-Rspam-User: X-Stat-Signature: ogsdfd4smitqfpjczcbk7fwoqsgxdmox X-Rspamd-Queue-Id: 74E6D40011 X-Rspamd-Server: rspam02 X-HE-Tag: 1728484181-953101 X-HE-Meta: U2FsdGVkX1+R3H0IU7JHkBZipwH2c416IAAHAqNkOcclcEciAxR27I5SegWDtVglhOG2yQPyctCDfcgU7OhlbelKJZaVMbLop5n0yTuqD7ho+A8wWRqxXy21r+t+tf/MAAQbTdot8IrDT8bbBsYiug+Y9yYXZQcjYK+atKsv0v8tWFyOC0cjerPBkh6qxgZwcT9/b2TCaX5zRMVMc8EGoeSjnqlsVlMs21ZwQ9wW7GywUMHN/cfCyA3jzsJPObjaGqqMdlMG28G7xb0A27raTs9AtlPtR2SD07heBVByBnzdVXhMEnKm+j5MrovexVwWZ4OWBIV/KcXsq2HLGlmOy/WxsWdDCn7TgaJZM53xnu3YEy47D/9ALrnyhDIJ/H1Wd5nL1f/Vp8V5nnNGjhGQR5eXkcF4ih2dvB2sztaaND3Z+SB7jutjXqGTeJ8azcehiKRlZ3W+oRtxigm8NrB4OraJsYMHX+t+9lNkNd5zHY1tDgl5AwtPATusZjpC5Z4x/zGy4Ulaa1WaTMnHvRtRGmm7coqrLP1pWKqtQ754Onaj6H4wrcsFXA6wn+hgEhgtTOd3UsI1Ai6bTS0oX/FWT+G/rCKhII2TyAZATqHxfsh6tNKV85DVN8O+IDg8s/cnCYok7bXzyXLtuPha9lBGQ8o5Mf90NglE0zu3UCyEx/FiD6f0KoWpVghfd66jM+cHdbwTzcCKiSGxqYDt5ATtP5LzZ6MBNlEGZMq84sLsrhIPJvWqRhs5k/GmHMkWT+i80plOQM6uNtN6fjorit5v8SOFBFrxEKH7iIRy/TAWyYzOQTCaREmIBDSMb5XaMCXm+dC2rPv+pVKwI20W4HGrh7R02s2ymKo5kuq+W8f6xpz3Y2uGPAEhmX5h4NqOgEoe6bh4UzxsgWKufispFwq2/bOj6pVYXMHgVSvVYlYclhavvq3C0jJg1v1nitHpuaE1QgmElouC+MIFBMzwm0S 9PAR8IkQ XFb67YRAxSKOcIDIxlhB/sxAabVBJFl74C+9tycPKWHvNHqP1kakQmiivna4VmKnFa1kbvlYZm9B4Mb+Y+XVu/H2DjKeMRRLwHWWojY4Mv1iO4cBPzw42ZdyjRDAu8QO7TJpTt6ojqF+mIiIByAlXZIJ5MsiCwVWJmP9ryxW/nQ2vGpRtih2Rtmlm4YARiVBBlRy4IUO7xa0Ua2DPiqkJ1XOxEDqBuFK7omVD97HZJiBcW5A0lZpK6YENaWMdf5sdUgFPfZJgk5M73HyRYmCQleBn7RG6x1q3But5gg/4u5LJobW6JjpqJOphMQnG/OE7qfZsd30PEbXAX7nSIdV9VJeFoos3GzxkHKIWoEhoG4qYlpg= 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: We have many SLAB_ flags but many are used only internally, by kunit tests or debugging subsystems cooperating with slab, or are set according to slab_debug boot parameter. Create kerneldocs for the commonly used flags that may be passed to kmem_cache_create(). SLAB_TYPESAFE_BY_RCU already had a detailed description, so turn it to a kerneldoc. Add some details for SLAB_ACCOUNT, SLAB_RECLAIM_ACCOUNT and SLAB_HWCACHE_ALIGN. Reference them from the __kmem_cache_create_args() kerneldoc. Signed-off-by: Vlastimil Babka --- I plan to take this in the slab tree, but a question for Jon/linux-doc: I think I'm doing properly the "Object-like macro documentation" for parameter-less macros from the doc-guide. Yet I can see in the htmldocs things like "SLAB_TYPESAFE_BY_RCU ()" and "Parameters". Is there a bug in the sphinx machinery? Thanks. include/linux/slab.h | 60 ++++++++++++++++++++++++++++++-------------- mm/slab_common.c | 14 ++++++++++- 2 files changed, 54 insertions(+), 20 deletions(-) diff --git a/include/linux/slab.h b/include/linux/slab.h index b35e2db7eb0e..49e9fb93e864 100644 --- a/include/linux/slab.h +++ b/include/linux/slab.h @@ -77,7 +77,17 @@ enum _slab_flag_bits { #define SLAB_POISON __SLAB_FLAG_BIT(_SLAB_POISON) /* Indicate a kmalloc slab */ #define SLAB_KMALLOC __SLAB_FLAG_BIT(_SLAB_KMALLOC) -/* Align objs on cache lines */ +/** + * define SLAB_HWCACHE_ALIGN - Align objects on cache line boundaries. + * + * Sufficiently large objects are aligned on cache line boundary. For object + * size smaller than a half of cache line size, the alignment is on the half of + * cache line size. In general, if object size is smaller than 1/2^n of cache + * line size, the alignment is adjusted to 1/2^n. + * + * If explicit alignment is also requested by the respective + * &struct kmem_cache_args field, the greater of both is alignments is applied. + */ #define SLAB_HWCACHE_ALIGN __SLAB_FLAG_BIT(_SLAB_HWCACHE_ALIGN) /* Use GFP_DMA memory */ #define SLAB_CACHE_DMA __SLAB_FLAG_BIT(_SLAB_CACHE_DMA) @@ -87,8 +97,8 @@ enum _slab_flag_bits { #define SLAB_STORE_USER __SLAB_FLAG_BIT(_SLAB_STORE_USER) /* Panic if kmem_cache_create() fails */ #define SLAB_PANIC __SLAB_FLAG_BIT(_SLAB_PANIC) -/* - * SLAB_TYPESAFE_BY_RCU - **WARNING** READ THIS! +/** + * define SLAB_TYPESAFE_BY_RCU - **WARNING** READ THIS! * * This delays freeing the SLAB page by a grace period, it does _NOT_ * delay object freeing. This means that if you do kmem_cache_free() @@ -99,20 +109,22 @@ enum _slab_flag_bits { * stays valid, the trick to using this is relying on an independent * object validation pass. Something like: * - * begin: - * rcu_read_lock(); - * obj = lockless_lookup(key); - * if (obj) { - * if (!try_get_ref(obj)) // might fail for free objects - * rcu_read_unlock(); - * goto begin; + * :: + * + * begin: + * rcu_read_lock(); + * obj = lockless_lookup(key); + * if (obj) { + * if (!try_get_ref(obj)) // might fail for free objects + * rcu_read_unlock(); + * goto begin; * - * if (obj->key != key) { // not the object we expected - * put_ref(obj); - * rcu_read_unlock(); - * goto begin; - * } - * } + * if (obj->key != key) { // not the object we expected + * put_ref(obj); + * rcu_read_unlock(); + * goto begin; + * } + * } * rcu_read_unlock(); * * This is useful if we need to approach a kernel structure obliquely, @@ -137,7 +149,6 @@ enum _slab_flag_bits { * * Note that SLAB_TYPESAFE_BY_RCU was originally named SLAB_DESTROY_BY_RCU. */ -/* Defer freeing slabs to RCU */ #define SLAB_TYPESAFE_BY_RCU __SLAB_FLAG_BIT(_SLAB_TYPESAFE_BY_RCU) /* Trace allocations and frees */ #define SLAB_TRACE __SLAB_FLAG_BIT(_SLAB_TRACE) @@ -170,7 +181,12 @@ enum _slab_flag_bits { #else # define SLAB_FAILSLAB __SLAB_FLAG_UNUSED #endif -/* Account to memcg */ +/** + * define SLAB_ACCOUNT - Account allocations to memcg. + * + * All object allocations from this cache will be memcg accounted, regardless of + * __GFP_ACCOUNT being or not being passed to individual allocations. + */ #ifdef CONFIG_MEMCG # define SLAB_ACCOUNT __SLAB_FLAG_BIT(_SLAB_ACCOUNT) #else @@ -197,7 +213,13 @@ enum _slab_flag_bits { #endif /* The following flags affect the page allocator grouping pages by mobility */ -/* Objects are reclaimable */ +/** + * define SLAB_RECLAIM_ACCOUNT - Objects are reclaimable. + * + * Use this flag for caches that have an associated shrinker. As a result, slab + * pages are allocated with __GFP_RECLAIMABLE, which affects grouping pages by + * mobility, and are accounted in SReclaimable counter in /proc/meminfo + */ #ifndef CONFIG_SLUB_TINY #define SLAB_RECLAIM_ACCOUNT __SLAB_FLAG_BIT(_SLAB_RECLAIM_ACCOUNT) #else diff --git a/mm/slab_common.c b/mm/slab_common.c index 744324465615..4d8353b601a6 100644 --- a/mm/slab_common.c +++ b/mm/slab_common.c @@ -257,11 +257,23 @@ static struct kmem_cache *create_cache(const char *name, * @object_size: The size of objects to be created in this cache. * @args: Additional arguments for the cache creation (see * &struct kmem_cache_args). - * @flags: See %SLAB_* flags for an explanation of individual @flags. + * @flags: See the desriptions of individual flags. The common ones are listed + * in the description below. * * Not to be called directly, use the kmem_cache_create() wrapper with the same * parameters. * + * Commonly used @flags: + * + * &SLAB_ACCOUNT - Account allocations to memcg. + * + * &SLAB_HWCACHE_ALIGN - Align objects on cache line boundaries. + * + * &SLAB_RECLAIM_ACCOUNT - Objects are reclaimable. + * + * &SLAB_TYPESAFE_BY_RCU - Slab page (not individual objects) freeing delayed + * by a grace period - see the full description before using. + * * Context: Cannot be called within a interrupt, but can be interrupted. * * Return: a pointer to the cache on success, NULL on failure.