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 041EACEE326 for ; Wed, 9 Oct 2024 16:11:21 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 88C056B00C4; Wed, 9 Oct 2024 12:11:20 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 83BEB6B00C5; Wed, 9 Oct 2024 12:11:20 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 68DA66B00C8; Wed, 9 Oct 2024 12:11:20 -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 485C26B00C4 for ; Wed, 9 Oct 2024 12:11:20 -0400 (EDT) Received: from smtpin10.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay08.hostedemail.com (Postfix) with ESMTP id 88BE91417DA for ; Wed, 9 Oct 2024 16:11:17 +0000 (UTC) X-FDA: 82654553478.10.6FF08A8 Received: from smtp-out2.suse.de (smtp-out2.suse.de [195.135.223.131]) by imf08.hostedemail.com (Postfix) with ESMTP id 5452E16001E for ; Wed, 9 Oct 2024 16:11:17 +0000 (UTC) Authentication-Results: imf08.hostedemail.com; dkim=pass header.d=suse.cz header.s=susede2_rsa header.b=JRmBRPPy; dkim=pass header.d=suse.cz header.s=susede2_ed25519 header.b=UpCUCcPH; dkim=pass header.d=suse.cz header.s=susede2_rsa header.b=JRmBRPPy; dkim=pass header.d=suse.cz header.s=susede2_ed25519 header.b=UpCUCcPH; dmarc=none; spf=pass (imf08.hostedemail.com: domain of vbabka@suse.cz designates 195.135.223.131 as permitted sender) smtp.mailfrom=vbabka@suse.cz ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1728490234; a=rsa-sha256; cv=none; b=4Q1Mdfkynibh11Hl891kMVEu4bB2mCWMIUxELMdGEczEjkJMJAS3LE/LK7LXqJwgR518mO 28YuwceipTLIeziAYwJ3Q++C87RXX2EExtF3SzxKGMS8dvPwxe/02GDZcmfq3cMu08Oqfi fKluhWHELaitUTcx837FGlE8mx3DFS0= ARC-Authentication-Results: i=1; imf08.hostedemail.com; dkim=pass header.d=suse.cz header.s=susede2_rsa header.b=JRmBRPPy; dkim=pass header.d=suse.cz header.s=susede2_ed25519 header.b=UpCUCcPH; dkim=pass header.d=suse.cz header.s=susede2_rsa header.b=JRmBRPPy; dkim=pass header.d=suse.cz header.s=susede2_ed25519 header.b=UpCUCcPH; dmarc=none; spf=pass (imf08.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=1728490234; 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:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=G4f8OY+mny5OIX5EQKRFIm7qlUVDzM4gfsFI3tA7AMc=; b=XziBg//5cT+kAS9c8EYVTKQh243BuvfF+YzI3M7hwvwy5/+MPn1Uiu3CzCe4idVS8n62Te IgfaKTKRxNtdOxg6pmEtyDdpkKBv9XcXwhRC4YhjYSN5YolYz66jLrh5VFRmJRKanVo3kg RQF8/7GYWkM7LRw3dZ0SDUVt58C+u9Q= 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 97C641FB5A; Wed, 9 Oct 2024 16:11:15 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1728490275; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:autocrypt:autocrypt; bh=G4f8OY+mny5OIX5EQKRFIm7qlUVDzM4gfsFI3tA7AMc=; b=JRmBRPPybtviL8RYVdRfjoLbFe1rN5A9LUDsbPOAoRsfmYm6uaBfjNMctPh4i3Mn2bOaNP jtYhGeJu+hlqCpCdShO1bABJIvrrK55v/5zgF3P7AQNxC0LBQr/+rDm/xdwbXLkSOCIaxk 8b1ZPdj1tSbM7cZmg/KyxkOulG4yfPk= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1728490275; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:autocrypt:autocrypt; bh=G4f8OY+mny5OIX5EQKRFIm7qlUVDzM4gfsFI3tA7AMc=; b=UpCUCcPHElRoSE9l9ChI3bbdlAMZHP2Rvwj79ky8pEZ0h5BRYaj+Z/xnnui8JWqZl+GWuI HcskvsDjlD3mR8AQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_rsa; t=1728490275; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:autocrypt:autocrypt; bh=G4f8OY+mny5OIX5EQKRFIm7qlUVDzM4gfsFI3tA7AMc=; b=JRmBRPPybtviL8RYVdRfjoLbFe1rN5A9LUDsbPOAoRsfmYm6uaBfjNMctPh4i3Mn2bOaNP jtYhGeJu+hlqCpCdShO1bABJIvrrK55v/5zgF3P7AQNxC0LBQr/+rDm/xdwbXLkSOCIaxk 8b1ZPdj1tSbM7cZmg/KyxkOulG4yfPk= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.cz; s=susede2_ed25519; t=1728490275; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:autocrypt:autocrypt; bh=G4f8OY+mny5OIX5EQKRFIm7qlUVDzM4gfsFI3tA7AMc=; b=UpCUCcPHElRoSE9l9ChI3bbdlAMZHP2Rvwj79ky8pEZ0h5BRYaj+Z/xnnui8JWqZl+GWuI HcskvsDjlD3mR8AQ== 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 805E113A58; Wed, 9 Oct 2024 16:11:15 +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 aiD6HiOrBmfYZQAAD6G6ig (envelope-from ); Wed, 09 Oct 2024 16:11:15 +0000 Message-ID: Date: Wed, 9 Oct 2024 18:11:15 +0200 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH] mm, slab: add kerneldocs for common SLAB_ flags Content-Language: en-US To: Jonathan Corbet , David Rientjes , Christoph Lameter , Randy Dunlap Cc: Hyeonggon Yoo <42.hyeyoo@gmail.com>, Roman Gushchin , Andrew Morton , linux-mm@kvack.org, linux-doc@vger.kernel.org References: <20241009142936.56092-2-vbabka@suse.cz> <878quxe2kw.fsf@trenco.lwn.net> From: Vlastimil Babka Autocrypt: addr=vbabka@suse.cz; keydata= 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 EP+ylKVEKb0Q2A== In-Reply-To: <878quxe2kw.fsf@trenco.lwn.net> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-Rspamd-Action: no action X-Rspam-User: X-Rspamd-Queue-Id: 5452E16001E X-Rspamd-Server: rspam01 X-Stat-Signature: ps8khbe11aqh9f3zg7831h36chs4mqd7 X-HE-Tag: 1728490277-128761 X-HE-Meta: U2FsdGVkX1+tTdsMrsi6AqpT+ZhfqAVE1ZoZxo0EMN6Ze+uRoysUJgp2O37S2vUbbv/nz3GtdXBHdOvLHw0LJgpaupTTE3DKi5py38xv5KrZBARhBzm1d6UrUJKguyPRnQXjlptnEiwgL83XG7a6W7HX217I+RMVmFsi0W7e4Zsl9XHMwrlNS1PEsvOC5uoEgM28zGYKrZZBERwBYqxOdm2OXOHqG4CNIhwZjH0UwHge8eVzMk3Jj/PNVBcByyNVkvHYh9JjnTZS629cHI0WB9ziBUJF49WNGMNnF9eYL/KSgSet229t4Wqkc3ZkfTH8dEjRj9efNzXfjarXvgDuiG3mV+l9c0Ta5FoTaqcQY9sqZojCPdf7wqASQBf1Ac3JzhkVSlSnxDB/NZmT3fXTHlOlnUwYYwWd4WSpJg24j5+BKlOVT9hGYHFvaMBpvCziMq2/RcoRgPa5jZCVyhwRQ3W32Q3p96S7U9rYINcyujIB1JObwNL3tvADCCQvDJR/0auexKKnjqjxRY40YbxnpvGlY49Yvx58DbLzreT8o8GdgHkFlKMrUfg+Fs1NwK1j9+rsKl671ahPidUwl6qB1BqU+m0y4LRaHuDdhDwGZ+S9DAI+ANV8hRmkfFdYf4vn3wW+p7bq07IE4NZ9qEZWhD01E7/BnCDAKDUkHVrNp9fUgk1KpJ34M3aUQjJ18mWIbX2PHON7uFmS7RdP4vzJoRW8V+1NhubpfKSiEoNUzBojxdZIERo3v4m6qbOTeYiRutu6cF0OfGzyBCzfvWuDDlVk4Kp82p5Cp2WqS2ZDTPfJgVyOYxSWQL85gNzx2F8XFV4FyOS8bJO/HcR55WDjZXC+XhOcdpO4ydjhswxn0UZXPq83IrjAexM6pVL/+hlI4vQP6qg7L9LyQPCVyRWg7My847CDWcKGiTH/XH1ZJAKe8NEzJjIiKYLU4NmB8zAUkcAxOElOIAz+VTBSyEC uFSktLu4 +j5ZGRI0rBzYO+iazHSP3Ln+phQG9uHJNAL5hXiJsfjK7QAO/rmNwxwuMhy+dFjP3Mk3HUNMFNko43g0p3E4St7W9RS3vwAL2+yJshJpN1sVoYEUKHIREhSQksu9S4wsqgc2HYLAY2YNeofzEJ+1mcGWouR0E5/l7acipPQXSd1V4Saym+34ujKej3M5dVDvFPgCd59QftSpBESL2JoCKjvTnNUsxTko35bRbDI7RIF+Z2ngQLJsYNe6zxWThO8aGz8CRlApQyNThulahkT4lbz7n2wDExL3/5m4EAvMZGWkWNbpECkk80fEJaG4/Ows/IXEoKqQIX7ItTSqgv7knmF4alp7n1u/ELSLOzKRy69FpKzdeyzk9S0oJyxYniq49LFU7SqdBfIH/zKKJXiy/1E7Z0A== 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: On 10/9/24 17:08, Jonathan Corbet wrote: > 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. I tried to follow the Documentation/doc-guide/kernel-doc.rst section "Object-like macro documentation" here. Looks like it's been added only in January this year via commit 91a3d6be99e63 by Randy and references commit cbb4d3e6510b implementing the support for that from 2014 (was it even sphinx based back then?) The DRM_GEM_VRAM_PLANE_HELPER_FUNCS from the example there still exists (include/drm/drm_gem_vram_helper.h) and seems to have the same rendering issue here. Somewhat weirdly it doesn't use the "define" keyword that the example does. DRM_GEM_VRAM_DRIVER in the same file does have the "define" keyword and with the same result. >> 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 for the hints. I hope if we can agree that documenting the macros was intended to be supported, doesn't break the build (there are users already) and has only those minor rendering issues, it can be used? > Thanks, > > jon