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 987933D9024; Wed, 18 Mar 2026 14:32:33 +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=1773844353; cv=none; b=NF20/xqmCg6UQ/ZDTjeUOnCQX6Sno2FPywL8vBogzAxfPVbcsaWHRx3x65E2cTTnboV6jwCVuN1NbuPpG6g54bSlryqsD5xPoG895Or5HJvmxt8R5AT1CLKeJybL41XLv7dT8WJNpeH/VeMN0X1uiV/U8TqL9eEaf+J+gdZQoGc= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773844353; c=relaxed/simple; bh=BkmNwvxpHD2rLSHreIl/KbDAd8IvuTpcKZIoErK/PhU=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=nDWr0bJo4Ai5aJMv0mvOa1xg8EIjeBDXSfMX44nUhnG11sBPyhfWfWkR9QrD1om0+fDPq7Tn0wM5NO5eDfrfAhDUHa1bWek4qgV7G4T32084hYo0WNtNffOsb4R/pBDK/cKWFldW355Co4IuhOqDBR3/KL4gYyeXsbwFV2yvy+8= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=bMiZeZar; 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="bMiZeZar" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 17D4BC19421; Wed, 18 Mar 2026 14:32:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1773844353; bh=BkmNwvxpHD2rLSHreIl/KbDAd8IvuTpcKZIoErK/PhU=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=bMiZeZarKo0I6In8lAdDvOsPtB+Akkqq5eFK8sm/YRM5xM4gSk3GswcKWLx9V8CPt +6YYl1xS3tNFIQTKhM40jfz1qPoTtm1elg0NV868yjkd5chJjTqeJgEOV6/CjRxzkT mQDFtdNKBQ/xnnBOebXJ71uzotCfxEva6Zj23n1drQV+9WtCXRpVecdCosRr9wxlY6 vtHhNHxZOYqX6DbExKyJvA7EW6fnoLWGHN6VIBgcwGz0PUL81aWr7tYmmCfeBlaDZE JbKmbSr+/Nh08b6WAlxfXt1VYRX2lavS093MPyeFA2L5/Ib4WDc+a58iauuYvq8QNp QgG84UCJntIbA== Date: Wed, 18 Mar 2026 10:32:31 -0400 From: Sasha Levin To: Jonathan Corbet Cc: 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> 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: <87h5qe9wig.fsf@trenco.lwn.net> On Tue, Mar 17, 2026 at 11:49:27AM -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? > >It would be nice to only have one way if at all possible; I'm sure that >crossed your mind at some point :) If there have to be two, having both >examples describe the same function would make the parallels more clear. Woops, I forgot to finish writing my reply to this :) Under the hood, kerneldoc specs are translated into those macros so they could be part of the build process and embedded into the resulting binary (both for documentation as well as the runtime validation). I don't think anyone would use the macro format directly, but as it's there anyway I figured I'd offer it as an option. Would it make sense to just hide it behind the scenes? -- Thanks, Sasha