From mboxrd@z Thu Jan 1 00:00:00 1970 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 BC57BCEDDA3 for ; Wed, 9 Oct 2024 15:08:36 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 545456B00C3; Wed, 9 Oct 2024 11:08:36 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 4CDB06B00C4; Wed, 9 Oct 2024 11:08:36 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 36E8C6B00C5; Wed, 9 Oct 2024 11:08:36 -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 14CE36B00C3 for ; Wed, 9 Oct 2024 11:08:36 -0400 (EDT) Received: from smtpin07.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay05.hostedemail.com (Postfix) with ESMTP id EC6C541646 for ; Wed, 9 Oct 2024 15:08:33 +0000 (UTC) X-FDA: 82654395390.07.DB766B1 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by imf29.hostedemail.com (Postfix) with ESMTP id DE10B12000B for ; Wed, 9 Oct 2024 15:08:33 +0000 (UTC) Authentication-Results: imf29.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b="fq/TkUyE"; spf=pass (imf29.hostedemail.com: domain of corbet@lwn.net designates 45.79.88.28 as permitted sender) smtp.mailfrom=corbet@lwn.net; dmarc=pass (policy=none) header.from=lwn.net ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1728486444; a=rsa-sha256; cv=none; b=k07fbaMrHOxOXkDYEqg+BMgdJx2jez+S7wCKB5jXDclUvgfx8mdLk5k8qnyQCxf3kqpW96 22IsNxpXviUAHq8OfLRZYV7NGDQjN2ZUTY5ckIC4RpdAqGcE1pcKMcX3MUEcnPievZRyyR WLmFTpFsqoCAsykmGOAC4/CW27PErls= ARC-Authentication-Results: i=1; imf29.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b="fq/TkUyE"; spf=pass (imf29.hostedemail.com: domain of corbet@lwn.net designates 45.79.88.28 as permitted sender) smtp.mailfrom=corbet@lwn.net; dmarc=pass (policy=none) header.from=lwn.net ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1728486444; 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-type:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=BL87GI+Y/jElrV0w5SRRmKiaish3bRMayxIczYzcdUo=; b=L1H0nn9CwM6T3xwpfCbOTDH8IXPvhKHVC6u4tLklWzooSyi4+s59NVgtqpVb8CrHVWsdGJ U3tDDBYOyVYpnD/Y4brZ2SsMLQgz2MYCJWD3JNQVlnUWCnG5BJ3Wgie56TI2v28hgi6XT1 DObB1pS6hx9pXY27ArCLA3RyvquduAY= DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 036A942BFE DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1728486512; bh=BL87GI+Y/jElrV0w5SRRmKiaish3bRMayxIczYzcdUo=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=fq/TkUyEa4MuaGUpPeTAuxtSctb5kiILcC3+yWQAODTcPqR2390X5jMEnZDlPr7FF rbAn+NMtnCm5KHoYxysBmsqeyCGwF0lsEWASpLCYKJSbJg8QpVF1okSu37wDny2aXe sg3gm/BvIOTSlveOwPQASzSj6ze7nV/MXKceSd+w31UvE7yRaxz4uEd3pED5RtC5qG vzft8ifr9R5/6viUf9dSwlXDgW49V8Z0eudIQi/mw//eUsZ6gOkd5Q5m0ElER0X8Hp vlizqZZFGkwMsZfnfxPOuvgZFTF43HgrwTo003ajIkFBXPAU2nv0/2bGFK5zJ1Ezqn +xlGwlEhN67sQ== Received: from localhost (unknown [IPv6:2601:280:5e00:625::1fe]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id 036A942BFE; Wed, 9 Oct 2024 15:08:31 +0000 (UTC) From: Jonathan Corbet To: Vlastimil Babka , David Rientjes , Christoph Lameter Cc: Hyeonggon Yoo <42.hyeyoo@gmail.com>, Roman Gushchin , Andrew Morton , linux-mm@kvack.org, linux-doc@vger.kernel.org, Vlastimil Babka Subject: Re: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags In-Reply-To: <20241009142936.56092-2-vbabka@suse.cz> References: <20241009142936.56092-2-vbabka@suse.cz> Date: Wed, 09 Oct 2024 09:08:31 -0600 Message-ID: <878quxe2kw.fsf@trenco.lwn.net> MIME-Version: 1.0 Content-Type: text/plain X-Stat-Signature: d1yxzghym7gyko1ptx4c51uox7hgz6wi X-Rspamd-Queue-Id: DE10B12000B X-Rspam-User: X-Rspamd-Server: rspam10 X-HE-Tag: 1728486513-218443 X-HE-Meta: U2FsdGVkX1+AiH8/TSxK4wU7pbG0vW/h4BNUpBCfITO8vzZz7Bh6aH6zIGgpbnv/4JPUTuLBVIMM7xgxaObwxxfUZ1JedgWugNbA7u2dpr/yvsQYvx2SXJTMwYZnIF6VoiquFo8O2RHViLFq/qLO/HUfFi2OB3u+RixrU5oL2zkuYm/f7B0VmjYSvRK8iqaZvEamQbZqCYDmk6coERfL2gQI89L6qOXHhD9XxsTktHRf6H+lGgaG2FuU/f3GRHqA24CutTl5M2dTk0juO4vjVwNFdhdqpIoM/8/oRFNdWyHrPmPGlbSw+ckv8juW90JPQwNG71WEriAFbHshkwdLAfuMIczDuyT2xzMLBAvYS1+qarjmjqPuezOd1k0JC1G0tnR9Dleg6AAMmhNbxcnfkuvqkTcoh/tCvZi8Zzb5L3gaMVIDh1WLzM3OodnL1vr5KKbFaSex6T1VgQ5Ao4EPQ9W2FQt6FXCNH5YZJHz/jjIM2tkUNwgvaISdQJRey1XYpsy8n4hXFiRQbTFXcXWrmpxn26upDWktXeEYp6haUFquEE21c8fHtVwOcTmt+KLUTN/YT/WtyvLQYmtqkH+QeZaUmPOuz4xhBA+J81ZwPRFkttXBZEU3a3XBUQvFvVDBhSdjPyp5m8FZdzGzgKI30/kOzDcO0nNf+5Na8dQ3yqXD7EhYciSD9gHAc1m9D9zFi2M36svTtf42Lt2LXtrTNMOmSTIje1ogugLpGhOt5fn9aGndBijOA/Mj5987l4prUsOlI7lPcnKSHh374V4biGgG2lCWA9IvgXkBUEsWhGKmfM45FTtQBfiANOLqyAL3aKPyCyd+sfiivxBm+dG4GfoYPWdaJSZt3pW8IdHfvG7QPJsUHqQfX48ws/4V9iPXBkSMCID6i7I2GrLzB1M7Dhim61tVxR5+qjKbLblWagWAZw/XtsFthI3EeUzl6m7cnBN1F+ltF7gRUgVFCqS 1qZssSt5 FnZyV75A5EhbgohlCThbAY5jjwCy0om14VrgwjxC5W0iIChGzBlsyelcU24L2ERYbLYemIWfjzk4Al2ya94SJ1WtNc3hssBXmP/aZ7zg6FXXB/L4HwJmW15JiAoe0F6vYBmrPpsmUu6kj+VzIXIBghoP2ABGIJS2SbBQ7JpEI5U5IRV+Pz/i244pD4Jl6N89DY3oFx1zTrPmAy+YbOfB7YmiIkCSuFXLHCYCfU1IyFXE66L110E7mdNq5eqK/5QLX7FwbH9F2LByaX3bzdEWtji+NCVsm58ORtJFodr/eLqT4tHYpeZ8w2cp9MlwWVlOuN3lBFnpK7F0aGSpTwQi34fPQNtajPMiqLrsrJ1AP0dXRiE4= 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: Vlastimil Babka writes: > 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. No, it's totally bug-free and any appearance to the contrary is entirely in your imagination :) I don't think anybody has tried to do kerneldoc for macros that don't look like functions; it doesn't surprise me that it doesn't work right. > 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. I'm kind of surprised that kernel-doc doesn't complain about that; it's definitely not something that was ever envisioned, as far as I know. Making it work properly probably requires somebody to wander into Perl regex hell. In the short term, if you want to get this text into the rendered docs, the usual approach is to make a DOC: block out of it and include it explicitly. Thanks, jon