From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-qv1-f43.google.com (mail-qv1-f43.google.com [209.85.219.43]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 96497282F29 for ; Sat, 14 Mar 2026 22:44:43 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.219.43 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773528284; cv=none; b=JOGO+KYxhiKTJehmJ+vs8bNdqjX8bFpouGAhrC7d0XpAykey8rBzHJ4De53Y+3ECAtOJxWq4S1sxUlxade1SUVVH9JEbbr1vhs0zxVMgeszpbwu+Kr/z4RXVfT/tgo9FdLzHQL6KuM1EjD5p+Plf3mEKKVCZHGxP6FHmwTTsFcA= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773528284; c=relaxed/simple; bh=+BzfWIbWutBn9FVLenIu2cDO6fBukYew6iGg+YJ9bLU=; h=Date:From:To:Cc:Subject:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=b0Se4qNJsku1BqBzC7omxBxo09Hnw0pA2qj/RoVIQmzV7nqQ+bo/tjVmJEyyhmmrhy6IXBpcLMsbUd2/y1aCVHjSLRx5FpKkfkwNXi6n7NbvoQV63TYp1a5KEFg92nZhwS7kAnhAN1rBUXr4xpAXzJW6PBN/MJB65bxsZHODdHI= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=HUHvKzBF; arc=none smtp.client-ip=209.85.219.43 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="HUHvKzBF" Received: by mail-qv1-f43.google.com with SMTP id 6a1803df08f44-89a6ac6f389so44841366d6.3 for ; Sat, 14 Mar 2026 15:44:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1773528282; x=1774133082; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:subject:cc:to:from:date:from:to:cc:subject:date :message-id:reply-to; bh=nuJUhym4M/ZFIJ+HRVLrIiZVMxaVq6Aogwi4UFclA/I=; b=HUHvKzBF5hhX4JfsIma2dg7iVHahQVXvhnXj8AsIHtXNbMgTUuSYsPwy8VLT9xnEzF EeX7jt9RC7YfoK+BU25zJMWlMfztSjsh3LnnNpj0z0DyMWJqPXNAXYzgXzCr8TyUV0E8 QwN8SbxvwIoa1lZiVk+/ugNlZzDW5T1SeilDNtenbONU4IVtyDb5jrAkYPnnyjoXawjR Eox8mi29T0lZpOE9gmj0Fedk5acbLbj8L20uDD9X1MIqxRUUFgjHdJj4pPZRH+cX/WKG FVAixQnIPaGULYn/1rQ5NgpgG4pP3cblsCvSepBTlhftfQ/CD85LZ15xbYP44UzQuVmT HPzg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1773528282; x=1774133082; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:subject:cc:to:from:date:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=nuJUhym4M/ZFIJ+HRVLrIiZVMxaVq6Aogwi4UFclA/I=; b=oS+197MNdqTRX/6ad0XPdE9+y+Evr0SKpGoE5IvjKnu0FFIN2J+qmjhi0Q2QNwRlP1 QgMeVlJfFL71H1i/HITROY+/NY+OcbfB2ql1hWD3bfKj8uzfj0qA+gJuVh2NjSp5YPl9 HkxgKNupm1BUHgZ8Qi+M1k0UuzVFU65rHP2JgEn5rqlLz1+cmn9Qy5tkGnmXjTNLBMqv DCwMlXZw3mpVZvPwhNqIyjz9VOeW9PdxI+xToIKRGSaStVrfT6+HcMz0JEgwY+SI6ERQ /RtyvBZt+hrhQzn4N9TwX13b05ti+XYjT/WVoLfO7iohCiZR5YRBLjSuhpLmSchH93uy hVDQ== X-Forwarded-Encrypted: i=1; AJvYcCVqZPYobLCar+EpoIP8QpFZ1Vkg/ZDMjuBPh7G2y4akrD9zxKboHvJNg7zKkptZRCV3ZnhejNsRyHz/CTkK@vger.kernel.org X-Gm-Message-State: AOJu0YxBCTAaXdT7fb8FWnt8sr6mncQwNDBbMrQBwLGuTioGnscHUp5y aRb13b2tN6XgVWXTt96cgNZpywShjxN7QGiXvaEvlUhskysyD6rN6wDz X-Gm-Gg: ATEYQzwAdbnKtGAeCIrHtXH7p0Q7dXRD4eRCx4U856AVu79Isk23y1Slaqvi6PGFZFB kJJ9xalGWQ0uaOxFe8ry+9i9xbQN7S0HSs2ej6jLKNsxSfmrLg1hHlZYjseLyeNG1lCGxsjqL2z v0gaBHn41kY/dxhYjz6DM+77RdWUZH9q7gJMUFFzvfasiFSs6RBwXkD8oIDBgbfTl4nFqpGQPbC MabGkXIDVxSOS6nMsvy6Ssp8FKlJmCAPV9ei94mu5WLURIdYTSWFxfyvcs9RYbqNYAZaOQ3XTou HWQWZeEmSwBhFtAcDDZrYLVb8loM4sPmVMi9hmIzjKlbP/dbd70k1l9GXJjzDatW9dSpxvUmnpN A0IKPurgDCqG123UoHpoY5uJdTwUxlGtj5r7ercbBymuqaeSrwX6gNj+lgRtXcOcnnasgG+eJqk gD7f/3K0X8co0dEENDD1iSrDST2JWcSdvqlOTgcZQGjaAM+kwjtW/3c1TJ+ZGnvU8l X-Received: by 2002:a05:6214:529d:b0:89a:173d:9c54 with SMTP id 6a1803df08f44-89a81cb9be9mr117730886d6.8.1773528282565; Sat, 14 Mar 2026 15:44:42 -0700 (PDT) Received: from pumpkin (82-69-66-36.dsl.in-addr.zen.co.uk. [82.69.66.36]) by smtp.gmail.com with ESMTPSA id 6a1803df08f44-89c43bb47c3sm11296526d6.14.2026.03.14.15.44.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 14 Mar 2026 15:44:41 -0700 (PDT) Date: Sat, 14 Mar 2026 22:44:35 +0000 From: David Laight To: Jakub Kicinski Cc: Sasha Levin , 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 , Jonathan Corbet , Dmitry Vyukov , Randy Dunlap , Cyril Hrubis , Kees Cook , Jake Edge , Askar Safin , Gabriele Paoloni , Mauro Carvalho Chehab , Christian Brauner , Alexander Viro , Andrew Morton , Masahiro Yamada , Shuah Khan , Ingo Molnar , Arnd Bergmann Subject: Re: [PATCH 0/9] Kernel API Specification Framework Message-ID: <20260314224435.35465615@pumpkin> In-Reply-To: <20260314111822.63a2ba4a@kernel.org> References: <20260313150928.2637368-1-sashal@kernel.org> <20260314111822.63a2ba4a@kernel.org> X-Mailer: Claws Mail 4.1.1 (GTK 3.24.38; arm-unknown-linux-gnueabihf) 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 Content-Transfer-Encoding: 7bit On Sat, 14 Mar 2026 11:18:22 -0700 Jakub Kicinski wrote: > On Fri, 13 Mar 2026 11:09:10 -0400 Sasha Levin wrote: > > This enables static analysis tools to verify userspace API usage at compile > > time, test generation based on formal specifications, consistent error handling > > validation, automated documentation generation, and formal verification of > > kernel interfaces. > > Could you give some examples? We have machine readable descriptions for > Netlink interfaces, we approached syzbot folks and they did not really > seem to care for those. The whole thing reminds me of doxygen comment blocks. They tend to make it hard to read the source files, hard to search the source files (due to all the extra matches) and are pretty much always out of date. The kerndoc comment blocks for trivial helper functions are hard enough to keep up to date. The only way even parameter descriptions are going to stay correct is if the compiler is using the definition and only the comment part is extra. For error returns you'll need the documentation to be at the return site. David