From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-qv1-f46.google.com (mail-qv1-f46.google.com [209.85.219.46]) (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 912AD823DD for ; Sat, 14 Mar 2026 22:44:43 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.219.46 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773528284; cv=none; b=ar10X0JFrGLT1jK8C6hzyTeWmmk+TlvGtoWtzryvYBl7PQ83V0/LBFh5m/A4Jrx9y5sAH40eDwvuIqHIl6cz5QSu42fV19z/yOFvPw/YUUSA0uH3Hpsb7i3y0rbKm4+UQTHOg8zMTfqDFh3YRSn8f61VCdrUZvSGsEJ5olHSfos= 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.46 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-f46.google.com with SMTP id 6a1803df08f44-89a09ef1e3aso44892526d6.0 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=E8JTJlWi+75/8ETF4/HXAY/Es30Kq2AmTlFmWZPHEFaiDNH/nzYIZeuNT4Mwkn1Owg OCcTw2gvycv4EAgmb8VtvK5UgYcUhihNdO9+S39p/xZyhaONicQBQ6DaEYXwhZulkuR7 QtW0kyhALRmzMDdtp4gjxLWxh5clOOE94le8fuoEF4unyoXO8S/U7V5Qyuo6Bj5uWwHL 9/L4+rJe6VbOUHarVPWospzRs3R1vccvLYseLsit1J7txHty5vOxgNQT7z0k9Dq7eynH uGb3fQ2Dp/nQf7DJFECEtrhHzHM+XDmLhgfBrMroDPfiRM8+kX6trMrECLu70jrD1cdC SjSA== X-Forwarded-Encrypted: i=1; AJvYcCUJFv4m6e701l1Jj+GSDG4FAtOhI9tiVyL+MxgpYzZHKL/l8r11EJiFHXIHk4nno6E5YnA8MFgNrrz7MZA=@vger.kernel.org X-Gm-Message-State: AOJu0Ywsy6mDz0ak3QdlcnjapgtASNEMGwODMZ6o94XKx9OYbJERrWEl ipzYgUt/MT8elZQaFLl86ikaCt2MQJ+vAmNZLM9+Ob5787/jB75dDi0rmXlOwUu6 X-Gm-Gg: ATEYQzxz05DXF/mmGJE2wVNU8ssTUmPwl6JvIihP3fqgbgrAwG1PVGgxlmA5jXVLsEw tOCOHWb+wP1zUVckVsWDm0wE1nJfJIC8uzbH5IUAgdkKV9EASi2u9IRKbC4fAO2QKUr8LyZ/nAS a3q/a6RrhHNbQPG7VuhS9dzXlM/9hXkDuv9PtSo37g6MCl8v6tS0XFkZnfdyD1/wIKc5pC85Yyi bdS1fytIQ3nEA/xMb4FDwJt+atAkdaX1i1kNZPEqcy1jND6unBvKMTm9wzuD3Bh6JP818WZKvtg u+ouD/N7DzkwqStB4QYtceF9acRbj2Q2g0TAapE/dThDogAB6fmpb1JOSWFf1zt2MleJy10NZ0Q T4E8RpILDqFuEAQbL85xag/0kqDF72alFvo4rINBJjbw0qNclrdgzADvcxAKcUf8GT5Yfmm+1Hk wP82knZLHEO9V79i3vT+nPMmUIj4wNdFJlu3ditCqZk3ywV2Uz8WhHaXvkSNzw+xqi 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-kernel@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