From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id BE08A3DA7F9; Wed, 18 Mar 2026 14:53:16 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773845596; cv=none; b=T4PezzOunG4LsgIp8xGtPoUKYj0ar/qLddB54FP5SeLPzbDlpQ1BxGFITTcRzfAsqiS36g+qTQaL/VD2VHVwJ0EmcMS622Xacu7bvNOqw5D74vod/slgHBDlK67Wou9V1MplpJbPk/+JgdpFDXJ3lpkxanDqsKC2zIxODLvekPQ= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773845596; c=relaxed/simple; bh=P3RmEfeVl5rB1RolpuEMWoYT1Rcb+L0pzJIV0hoByz0=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=JnR3tHnxcWIsvMci8/ZA7sqxZ8MMELKGvexir3hypxvEGl2biWlvDr/X4ztPK+2x2YpAf1zNh2J7hnqs7EEtbW4dYU5QTtOUQImp5h8GoIAzMT56QCo+gc19JaL0Mh8W/E5XsqwvcLjFIks55CR+RmVszHjG9XCE3xzPvQFRT+g= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=nMbtNwkb; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="nMbtNwkb" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2D76BC2BC87; Wed, 18 Mar 2026 14:53:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1773845596; bh=P3RmEfeVl5rB1RolpuEMWoYT1Rcb+L0pzJIV0hoByz0=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=nMbtNwkbW+OUuU+yZQ/XPWW5ssKtSEb4Ak7q/TSWFTi1wWOwPNs4+4ISaQx6iagfz SkjanjkVNtPWbP0meWOJ7lP8DKAX82gAY7qP/HO0qgwANKwBEaLX+UKQbaJw+D6C4l cR7MNfb7Ps3FMv0WCCEcuE7F6ICzla5fkKL5ZwacsE/BHx5ZsfODCGaESSn5M/1m9Y Iy0rqm72AtdPHXAKQKIj3JK0t2PTMahvgBoriZKu9XfHjus3xtxWEYsxtM+bB8/69G TbFSJHr6guXlhZ+mNEfKjW7nIs0+yBRKs+UvYe7qkKW6lSP3VJp0HT+Jq8r1Bu3hme l/qsqdQKh8ryg== Date: Wed, 18 Mar 2026 10:53:15 -0400 From: Sasha Levin To: Mauro Carvalho Chehab Cc: Jonathan Corbet , linux-api@vger.kernel.org, linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kbuild@vger.kernel.org, linux-kselftest@vger.kernel.org, workflows@vger.kernel.org, tools@kernel.org, x86@kernel.org, Thomas Gleixner , "Paul E. McKenney" , Greg Kroah-Hartman , Dmitry Vyukov , Randy Dunlap , Cyril Hrubis , Kees Cook , Jake Edge , David Laight , Askar Safin , Gabriele Paoloni , Mauro Carvalho Chehab , Christian Brauner , Alexander Viro , Andrew Morton , Masahiro Yamada , Shuah Khan , Ingo Molnar , Arnd Bergmann Subject: Re: [PATCH 1/9] kernel/api: introduce kernel API specification framework Message-ID: References: <20260313150928.2637368-1-sashal@kernel.org> <20260313150928.2637368-2-sashal@kernel.org> <87h5qe9wig.fsf@trenco.lwn.net> <20260318070055.39f1af80@foz.lan> Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Disposition: inline In-Reply-To: <20260318070055.39f1af80@foz.lan> On Wed, Mar 18, 2026 at 07:00:55AM +0100, Mauro Carvalho Chehab wrote: >On Tue, 17 Mar 2026 11:49:27 -0600 >Jonathan Corbet wrote: >> So the reason for two completely separate mechanisms is not entirely >> clear to me. The kerneldoc variant is essentially documentation, while >> the macro stuff is to be built into the executable? What if you want >> both? > >You can easily add support at kernel-doc to output such macros. > >All you need is to create a new class derived from OutputFormat and >make it produce any different output format, including: > > #include > > DEFINE_KERNEL_API_SPEC(sys_open) > KAPI_DESCRIPTION("Open or create a file") > KAPI_CONTEXT(KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE) > /* ... parameter, error, constraint definitions ... */ > KAPI_END_SPEC > >I'd say that converting from such output to `.kapi_specs`` ELF section >itself and/or to sysfs/debugfs - e.g. something that would require to >compile or be linked with Kernel's compiled binaries should be done by a >separate tool, but we should aim to have a singe tool to process >kernel documentation markups. > >It is hard enough to maintain just one tool - and to have people actually >writing documentation. Having a second one to handle it, with a different >format will likely increase a lot the documentation burden. So this is exactly what happens under the hood :) kerneldoc outputs these macros and they get compiled ito the binary. I exposed the macros as an option since they're there anyway, but I'm happy to hide them as internal plumbing too. -- Thanks, Sasha