lists.openwall.net   lists  /  announce  owl-users  owl-dev  john-users  john-dev  passwdqc-users  yescrypt  popa3d-users  /  oss-security  kernel-hardening  musl  sabotage  tlsify  passwords  /  crypt-dev  xvendor  /  Bugtraq  Full-Disclosure  linux-kernel  linux-netdev  linux-ext4  linux-hardening  linux-cve-announce  PHC 
Open Source and information security mailing list archives
 
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [thread-next>] [day] [month] [year] [list]
Message-Id: <20250711114248.2288591-1-sashal@kernel.org>
Date: Fri, 11 Jul 2025 07:42:44 -0400
From: Sasha Levin <sashal@...nel.org>
To: linux-kernel@...r.kernel.org
Cc: linux-doc@...r.kernel.org,
	linux-api@...r.kernel.org,
	tools@...nel.org,
	Sasha Levin <sashal@...nel.org>
Subject: [RFC v3 0/4] Kernel API Specification Framework with kerneldoc integration

This patch series introduces a framework for formally specifying kernel
APIs, addressing the long-standing challenge of maintaining stable
interfaces between the kernel and user-space programs. As outlined in
previous discussions about kernel ABI stability, the lack of
machine-readable API specifications has led to inadvertent breakages and
inconsistent validation across system calls and IOCTLs.

The framework represents a fundamental shift from macro-based API
specifications to kerneldoc integration. Instead of requiring developers
to write specifications using C macros separate from documentation, the
framework now leverages the existing kerneldoc infrastructure. This
unification means developers write API specifications as part of their
regular documentation workflow, with the build system automatically
generating machine-readable C macros from these comments.

Changes since RFC v2:

1. Kerneldoc Integration: transition from C macros to kerneldoc
   comments.

2. Structured Parameter Specifications: Support for complex data
   structures with field-level constraints, including ranges, enums, and
   validation groups.

3. Hybrid Documentation Approach: Core API specifications remain inline
   with the implementation for tight coupling, while extended documentation
   (examples, detailed notes, complex constraints) can be maintained in
   separate files under Documentation/.

Sasha Levin (4):
  kernel/api: introduce kernel API specification framework
  kernel/api: enable kerneldoc-based API specifications
  mm/mlock: add API specification for mlock
  kernel/sched: add specs for sys_sched_setattr()

 Documentation/admin-guide/kernel-api-spec.rst |  507 ++++++
 Documentation/userspace-api/syscalls/mlock.rst|  118 ++
 MAINTAINERS                                   |    9 +
 arch/um/kernel/dyn.lds.S                      |    3 +
 arch/um/kernel/uml.lds.S                      |    3 +
 arch/x86/kernel/vmlinux.lds.S                 |    3 +
 include/asm-generic/vmlinux.lds.h             |   20 +
 include/linux/kernel_api_spec.h               | 1527 +++++++++++++++++
 include/linux/syscall_api_spec.h              |  137 ++
 include/linux/syscalls.h                      |   38 +
 init/Kconfig                                  |    2 +
 kernel/Makefile                               |    1 +
 kernel/api/Kconfig                            |   35 +
 kernel/api/Makefile                           |   26 +
 kernel/api/kernel_api_spec.c                  | 1122 ++++++++++++
 kernel/sched/syscalls.c                       |  168 +-
 mm/mlock.c                                    |   85 +
 scripts/Makefile.build                        |   28 +
 scripts/generate_api_specs.sh                 |   59 +
 scripts/kernel-doc.py                         |    5 +
 scripts/lib/kdoc/kdoc_apispec.py              |  623 +++++++
 scripts/lib/kdoc/kdoc_output.py               |    5 +-
 scripts/lib/kdoc/kdoc_parser.py               |   54 +-
 23 files changed, 4574 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/admin-guide/kernel-api-spec.rst
 create mode 100644 Documentation/userspace-api/syscalls/mlock.rst
 create mode 100644 include/linux/kernel_api_spec.h
 create mode 100644 include/linux/syscall_api_spec.h
 create mode 100644 kernel/api/Kconfig
 create mode 100644 kernel/api/Makefile
 create mode 100644 kernel/api/kernel_api_spec.c
 create mode 100755 scripts/generate_api_specs.sh
 create mode 100644 scripts/lib/kdoc/kdoc_apispec.py

-- 
2.39.5


Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ