[RFC v3 2/4] kernel/api: enable kerneldoc-based API specifications

[Sasha Levin <sashal@kernel.org>]

Allow kernel developers to write API specifications directly in
kerneldoc comments, which are automatically converted to machine-readable
C macros during build.

Signed-off-by: Sasha Levin <sashal@kernel.org>
---
 kernel/api/Makefile              |  21 +-
 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 ++-
 7 files changed, 791 insertions(+), 4 deletions(-)
 create mode 100755 scripts/generate_api_specs.sh
 create mode 100644 scripts/lib/kdoc/kdoc_apispec.py

diff --git a/kernel/api/Makefile b/kernel/api/Makefile
index 4120ded7e5cf1..312d35179c78a 100644
--- a/kernel/api/Makefile
+++ b/kernel/api/Makefile
@@ -4,4 +4,23 @@
 #
 
 # Core API specification framework
-obj-$(CONFIG_KAPI_SPEC)		+= kernel_api_spec.o
\ No newline at end of file
+obj-$(CONFIG_KAPI_SPEC)		+= kernel_api_spec.o
+
+# Auto-generated API specifications collector
+ifeq ($(CONFIG_KAPI_SPEC),y)
+obj-$(CONFIG_KAPI_SPEC)		+= generated_api_specs.o
+
+# Find all potential apispec files (this is evaluated at make time)
+apispec-files := $(shell find $(objtree) -name "*.apispec.h" -type f 2>/dev/null)
+
+# Generate the collector file
+# Note: FORCE ensures this is always regenerated to pick up new apispec files
+$(obj)/generated_api_specs.c: $(srctree)/scripts/generate_api_specs.sh FORCE
+	$(Q)$(CONFIG_SHELL) $< $(srctree) $(objtree) > $@
+
+targets += generated_api_specs.c
+clean-files += generated_api_specs.c
+
+# Add explicit dependency on the generator script
+$(obj)/generated_api_specs.o: $(obj)/generated_api_specs.c
+endif
\ No newline at end of file
diff --git a/scripts/Makefile.build b/scripts/Makefile.build
index a6461ea411f7a..5c0e44d1b6dbc 100644
--- a/scripts/Makefile.build
+++ b/scripts/Makefile.build
@@ -172,6 +172,34 @@ ifneq ($(KBUILD_EXTRA_WARN),)
         $<
 endif
 
+# Generate API spec headers from kernel-doc comments
+ifeq ($(CONFIG_KAPI_SPEC),y)
+# Function to check if a file has API specifications
+has-apispec = $(shell grep -qE '^\s*\*\s*(api-type|long-desc|context-flags|param-type|error-code|capability|signal|lock|side-effect|state-trans):' $(src)/$(1) 2>/dev/null && echo $(1))
+
+# Get base names without directory prefix
+c-objs-base := $(notdir $(real-obj-y) $(real-obj-m))
+# Filter to only .o files with corresponding .c source files
+c-files := $(foreach o,$(c-objs-base),$(if $(wildcard $(src)/$(o:.o=.c)),$(o:.o=.c)))
+# Also check for any additional .c files that contain API specs but are included
+extra-c-files := $(shell find $(src) -maxdepth 1 -name "*.c" -exec grep -l '^\s*\*\s*\(api-type\|long-desc\|context-flags\|param-type\|error-code\|capability\|signal\|lock\|side-effect\|state-trans\):' {} \; 2>/dev/null | xargs -r basename -a)
+# Combine both lists and remove duplicates
+all-c-files := $(sort $(c-files) $(extra-c-files))
+# Only include files that actually have API specifications
+apispec-files := $(foreach f,$(all-c-files),$(call has-apispec,$(f)))
+# Generate apispec targets with proper directory prefix
+apispec-y := $(addprefix $(obj)/,$(apispec-files:.c=.apispec.h))
+always-y += $(apispec-y)
+targets += $(apispec-y)
+
+quiet_cmd_apispec = APISPEC $@
+      cmd_apispec = PYTHONDONTWRITEBYTECODE=1 $(KERNELDOC) -apispec \
+                    $(KDOCFLAGS) $< > $@ 2>/dev/null || rm -f $@
+
+$(obj)/%.apispec.h: $(src)/%.c FORCE
+	$(call if_changed,apispec)
+endif
+
 # Compile C sources (.c)
 # ---------------------------------------------------------------------------
 
diff --git a/scripts/generate_api_specs.sh b/scripts/generate_api_specs.sh
new file mode 100755
index 0000000000000..1ef817c0d1955
--- /dev/null
+++ b/scripts/generate_api_specs.sh
@@ -0,0 +1,59 @@
+#!/bin/bash
+# SPDX-License-Identifier: GPL-2.0
+#
+# generate_api_specs.sh - Generate C file that includes all API specification headers
+#
+# Usage: generate_api_specs.sh <srctree> <objtree>
+
+SRCTREE="$1"
+OBJTREE="$2"
+
+if [ -z "$SRCTREE" ] || [ -z "$OBJTREE" ]; then
+    echo "Usage: $0 <srctree> <objtree>" >&2
+    exit 1
+fi
+
+# Generate header
+cat <<EOF
+/* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * Auto-generated file - DO NOT EDIT
+ * Generated by: scripts/generate_api_specs.sh
+ *
+ * This file includes all kernel API specification headers
+ */
+
+#include <linux/kernel.h>
+#include <linux/kernel_api_spec.h>
+#include <linux/errno.h>
+#include <linux/capability.h>
+#include <uapi/linux/sched/types.h>
+
+#ifdef CONFIG_KAPI_SPEC
+
+EOF
+
+# Find all .apispec.h files and generate includes
+# We look in the object tree since that's where they're generated
+find "$OBJTREE" -name "*.apispec.h" -type f 2>/dev/null | \
+    grep -v "/generated_api_specs.c" | \
+    sort | \
+    while read -r apispec_file; do
+        # Get relative path from objtree
+        rel_path="${apispec_file#$OBJTREE/}"
+
+        # Skip if file is empty
+        if [ ! -s "$apispec_file" ]; then
+            continue
+        fi
+
+        # Generate include statement
+        # For includes from kernel/api/, we need to go up two levels
+        echo "#include \"../../${rel_path}\""
+    done
+
+# Close the ifdef
+cat <<EOF
+
+#endif /* CONFIG_KAPI_SPEC */
+EOF
\ No newline at end of file
diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index 12ae66f40bd7d..8e0be6b3eacef 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -109,6 +109,7 @@ sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
 
 from kdoc_files import KernelFiles                      # pylint: disable=C0413
 from kdoc_output import RestFormat, ManFormat           # pylint: disable=C0413
+from kdoc_apispec import ApiSpecFormat                  # pylint: disable=C0413
 
 DESC = """
 Read C language source or header FILEs, extract embedded documentation comments,
@@ -225,6 +226,8 @@ def main():
                          help="Output reStructuredText format (default).")
     out_fmt.add_argument("-N", "-none", "--none", action="store_true",
                          help="Do not output documentation, only warnings.")
+    out_fmt.add_argument("-apispec", "--apispec", action="store_true",
+                         help="Output C macro invocations for kernel API specifications.")
 
     # Output selection mutually-exclusive group
 
@@ -275,6 +278,8 @@ def main():
         out_style = ManFormat(modulename=args.modulename)
     elif args.none:
         out_style = None
+    elif args.apispec:
+        out_style = ApiSpecFormat()
     else:
         out_style = RestFormat()
 
diff --git a/scripts/lib/kdoc/kdoc_apispec.py b/scripts/lib/kdoc/kdoc_apispec.py
new file mode 100644
index 0000000000000..129fe5bf236a4
--- /dev/null
+++ b/scripts/lib/kdoc/kdoc_apispec.py
@@ -0,0 +1,623 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0
+
+"""
+Generate C macro invocations for kernel API specifications from kernel-doc comments.
+
+This module creates C header files with API specification macros that match
+the kernel API specification framework introduced in commit 9688de5c25bed.
+"""
+
+from kdoc_output import OutputFormat
+
+
+class ApiSpecFormat(OutputFormat):
+    """Generate C macro invocations for kernel API specifications"""
+
+    def __init__(self):
+        """Initialize ApiSpecFormat"""
+        super().__init__()
+        self.api_specs = {}
+
+    def _format_macro_param(self, value):
+        """Format a value for use in C macro parameter"""
+        if value is None:
+            return '""'
+        # Escape quotes and backslashes for C string literals
+        value = str(value).replace('\\', '\\\\').replace('"', '\\"')
+        # Handle multi-line strings by replacing newlines with escaped newlines
+        value = value.replace('\n', '\\n"\n\t\t       "')
+        return f'"{value}"'
+
+    def _get_api_section_value(self, sections, key):
+        """Get value from API sections"""
+        # sections is a dictionary where keys are section names
+        # Check both with and without @ prefix
+        if key in sections:
+            content = sections[key]
+            # Return full content, stripping trailing newlines
+            return content.rstrip('\n')
+        elif '@' + key in sections:
+            content = sections['@' + key]
+            return content.rstrip('\n')
+        return None
+
+    def _get_all_section_lines(self, sections, key):
+        """Get all lines from a section"""
+        if key in sections:
+            return [line.strip() for line in sections[key].strip().split('\n') if line.strip()]
+        elif '@' + key in sections:
+            return [line.strip() for line in sections['@' + key].strip().split('\n') if line.strip()]
+        return []
+
+    def _process_error_code(self, error_lines, error_idx):
+        """Process a multi-line error code specification"""
+        if not error_lines:
+            return
+
+        # First line has: -ECODE, NAME, Short desc, Long desc
+        first_line = error_lines[0]
+        parts = first_line.split(',', 3)
+        if len(parts) >= 3:
+            code = parts[0].strip()
+            name = parts[1].strip()
+            short_desc = parts[2].strip()
+
+            # Collect long description from remaining parts and lines
+            long_desc_parts = []
+            if len(parts) > 3:
+                long_desc_parts.append(parts[3].strip())
+            # Add continuation lines
+            for line in error_lines[1:]:
+                long_desc_parts.append(line.strip())
+            long_desc = ' '.join(long_desc_parts)
+
+            self.data += f"\n\tKAPI_ERROR({error_idx}, {code}, {self._format_macro_param(name)}, "
+            self.data += f"{self._format_macro_param(short_desc)},\n\t\t   {self._format_macro_param(long_desc)})\n"
+
+    def _parse_param_spec(self, param_name, sections):
+        """Parse all specifications for a parameter"""
+        specs = {}
+
+        # Look for parameter-specific sections
+        for key, content in sections.items():
+            # Check both param- and @param- prefixes
+            if key.startswith('param-') or key.startswith('@param-'):
+                # Remove @ prefix if present for specs key
+                specs_key = key[1:] if key.startswith('@') else key
+
+                # Each section may contain multiple parameter specifications
+                # separated by newlines
+                for line in content.strip().split('\n'):
+                    line = line.strip()
+                    if ',' in line and line.split(',', 1)[0].strip() == param_name:
+                        value = line.split(',', 1)[1].strip()
+                        specs[specs_key] = value
+                        break  # Found this parameter's value for this key
+
+        return specs
+
+    def out_function(self, fname, name, args):
+        """Generate API spec for a function"""
+        function_name = args.get('function', '')
+        sections = args.get('sections', {})
+        parameterlist = args.get('parameterlist', [])
+        parameterdescs = args.get('parameterdescs', {})
+        parametertypes = args.get('parametertypes', {})
+        purpose = args.get('purpose', '')
+
+        # Check if this function has an API specification
+        # Look for key API spec sections that indicate this is a full API specification
+        api_indicators = [
+            'api-type', 'context-flags', 'param-type', 'error-code',
+            'capability', 'signal', 'lock', 'side-effect', 'state-trans'
+        ]
+
+        has_api_spec = False
+        for indicator in api_indicators:
+            # Check both with and without @ prefix
+            if any(key.startswith(indicator) or key.startswith('@' + indicator) for key in sections.keys()):
+                has_api_spec = True
+                break
+
+        if not has_api_spec:
+            return
+
+        # Clear warnings for API spec output since parameter-specific sections
+        # trigger false warnings
+        args['warnings'] = []
+
+
+        # Start building the macro invocation
+        self.data += f"DEFINE_KERNEL_API_SPEC({function_name})\n"
+
+        # Add description
+        if purpose:
+            self.data += f"\tKAPI_DESCRIPTION({self._format_macro_param(purpose)})\n"
+
+        # Add long description if present
+        long_desc = self._get_api_section_value(sections, 'long-desc')
+        if long_desc:
+            self.data += f"\tKAPI_LONG_DESC({self._format_macro_param(long_desc)})\n"
+
+        # Add context flags
+        context_flags = self._get_api_section_value(sections, 'context-flags')
+        if context_flags:
+            self.data += f"\tKAPI_CONTEXT({context_flags})\n"
+        elif self._get_api_section_value(sections, 'context'):
+            # Fallback to simple context
+            self.data += f"\tKAPI_CONTEXT({self._get_api_section_value(sections, 'context')})\n"
+
+        # Add parameter count first
+        param_count = len(parameterlist)
+        param_count_val = self._get_api_section_value(sections, 'param-count')
+        # Note: KAPI_PARAM_COUNT doesn't exist in the current infrastructure
+        # Parameters are handled individually with KAPI_PARAM/KAPI_PARAM_END
+
+        # Process parameters
+        for param_idx, param in enumerate(parameterlist):
+            param_name = param.strip()
+            param_desc = parameterdescs.get(param_name, '')
+            param_ctype = parametertypes.get(param_name, '')
+
+            # Get all parameter specifications
+            param_specs = self._parse_param_spec(param_name, sections)
+
+            self.data += f"\n\tKAPI_PARAM({param_idx}, {self._format_macro_param(param_name)}, "
+            self.data += f"{self._format_macro_param(param_ctype)}, {self._format_macro_param(param_desc)})\n"
+
+            # Add parameter type
+            if 'param-type' in param_specs:
+                self.data += f"\t\tKAPI_PARAM_TYPE({param_specs['param-type']})\n"
+
+            # Add parameter flags
+            if 'param-flags' in param_specs:
+                self.data += f"\t\tKAPI_PARAM_FLAGS({param_specs['param-flags']})\n"
+
+            # Add constraint type
+            if 'param-constraint-type' in param_specs:
+                self.data += f"\t\tKAPI_PARAM_CONSTRAINT_TYPE({param_specs['param-constraint-type']})\n"
+
+            # Add range
+            if 'param-range' in param_specs:
+                if ',' in param_specs['param-range']:
+                    min_val, max_val = param_specs['param-range'].split(',', 1)
+                    self.data += f"\t\tKAPI_PARAM_RANGE({min_val.strip()}, {max_val.strip()})\n"
+
+            # Add mask
+            if 'param-mask' in param_specs:
+                self.data += f"\t\tKAPI_PARAM_MASK({param_specs['param-mask']})\n"
+
+            # Add constraint description
+            if 'param-constraint' in param_specs:
+                self.data += f"\t\tKAPI_PARAM_CONSTRAINT({self._format_macro_param(param_specs['param-constraint'])})\n"
+
+            # struct-type information is stored as comments for documentation purposes
+            # The actual struct validation happens in the kernel based on param type
+
+            self.data += "\tKAPI_PARAM_END\n"
+
+        # Add return specification if we have meaningful return information
+        return_type = self._get_api_section_value(sections, 'return-type')
+        return_check = self._get_api_section_value(sections, 'return-check-type') or \
+                      self._get_api_section_value(sections, 'return-check')
+        return_success = self._get_api_section_value(sections, 'return-success')
+
+        if return_type or return_check or return_success:
+            # Get return description but don't use generic ones
+            return_desc = sections.get('return', sections.get('returns', sections.get('Return', '')))
+            if return_desc and any(phrase in return_desc.lower() for phrase in
+                                 ['error code', 'negative error', 'success or error']):
+                return_desc = ""  # Skip generic descriptions
+
+            self.data += f"\n\tKAPI_RETURN({self._format_macro_param(parametertypes.get('', 'long'))}, "
+            self.data += f"{self._format_macro_param(return_desc)})\n"
+
+            if return_type:
+                self.data += f"\t\tKAPI_RETURN_TYPE({return_type})\n"
+
+            if return_check:
+                self.data += f"\t\tKAPI_RETURN_CHECK_TYPE({return_check})\n"
+
+            if return_success:
+                self.data += f"\t\tKAPI_RETURN_SUCCESS({return_success})\n"
+
+            self.data += "\tKAPI_RETURN_END\n"
+
+        # Add error count before processing errors
+        error_lines = self._get_all_section_lines(sections, 'error-code')
+        error_count = self._get_api_section_value(sections, 'error-count')
+        if error_count:
+            self.data += f"\n\tKAPI_RETURN_ERROR_COUNT({error_count})\n"
+        else:
+            # Count the error lines
+            error_line_count = 0
+            for line in error_lines:
+                if line.startswith('-'):
+                    error_line_count += 1
+            if error_line_count > 0:
+                self.data += f"\n\tKAPI_RETURN_ERROR_COUNT({error_line_count})\n"
+
+        # Process error codes with extended format
+        error_idx = 0
+
+        # Process each error-code entry (which may span multiple lines)
+        current_error = []
+        for line in error_lines:
+            # Check if this starts a new error code (starts with -)
+            if line.startswith('-') and current_error:
+                # Process the previous error
+                self._process_error_code(current_error, error_idx)
+                error_idx += 1
+                current_error = [line]
+            else:
+                # Continuation of current error
+                current_error.append(line)
+
+        # Process the last error
+        if current_error:
+            self._process_error_code(current_error, error_idx)
+            error_idx += 1
+
+        # Add lock count before processing locks
+        lock_lines = self._get_all_section_lines(sections, 'lock')
+        lock_count = self._get_api_section_value(sections, 'lock-count')
+        if lock_count:
+            self.data += f"\n\tKAPI_LOCK_COUNT({lock_count})\n"
+        else:
+            # Count lock lines
+            lock_line_count = len(lock_lines)
+            lock_req = self._get_api_section_value(sections, 'lock-req')
+            if lock_req and lock_line_count == 0:
+                lock_line_count = 1
+            if lock_line_count > 0:
+                self.data += f"\n\tKAPI_LOCK_COUNT({lock_line_count})\n"
+
+        # Process locks
+        lock_idx = 0
+        for line in lock_lines:
+            parts = line.split(',')
+            if len(parts) >= 2:
+                lock_name = parts[0].strip()
+                lock_type = parts[1].strip()
+                self.data += f"\n\tKAPI_LOCK({lock_idx}, {self._format_macro_param(lock_name)}, {lock_type})\n"
+
+                # Check for lock attributes
+                if self._get_api_section_value(sections, 'lock-acquired'):
+                    self.data += "\t\tKAPI_LOCK_ACQUIRED\n"
+                if self._get_api_section_value(sections, 'lock-released'):
+                    self.data += "\t\tKAPI_LOCK_RELEASED\n"
+
+                lock_desc = self._get_api_section_value(sections, 'lock-desc')
+                if lock_desc:
+                    self.data += f"\t\tKAPI_LOCK_DESC({self._format_macro_param(lock_desc)})\n"
+
+                self.data += "\tKAPI_LOCK_END\n"
+                lock_idx += 1
+
+        # Legacy lock-req support
+        lock_req = self._get_api_section_value(sections, 'lock-req')
+        if lock_req and lock_idx == 0:
+            self.data += f"\n\tKAPI_LOCK(0, {self._format_macro_param(lock_req)}, KAPI_LOCK_CUSTOM)\n"
+            self.data += f"\t\tKAPI_LOCK_DESC({self._format_macro_param(lock_req)})\n"
+            self.data += "\tKAPI_LOCK_END\n"
+            lock_idx = 1
+
+        # Add constraint count before processing constraints
+        constraint_lines = self._get_all_section_lines(sections, 'constraint')
+        const_count = self._get_api_section_value(sections, 'constraint-count')
+        if const_count:
+            self.data += f"\n\tKAPI_CONSTRAINT_COUNT({const_count})\n"
+        elif len(constraint_lines) > 0:
+            self.data += f"\n\tKAPI_CONSTRAINT_COUNT({len(constraint_lines)})\n"
+
+        # Process constraints first (before signals/capabilities/etc)
+        constraint_idx = 0
+        for line in constraint_lines:
+            parts = line.split(',', 1)
+            if parts:
+                name = parts[0].strip()
+                desc = parts[1].strip() if len(parts) > 1 else ""
+
+                self.data += f"\n\tKAPI_CONSTRAINT({constraint_idx}, {self._format_macro_param(name)},\n"
+                self.data += f"\t\t\t{self._format_macro_param(desc)})\n"
+
+                # Check for constraint expression
+                expr_lines = self._get_all_section_lines(sections, 'constraint-expr')
+                for expr_line in expr_lines:
+                    if expr_line.startswith(name):
+                        expr = expr_line.split(',', 1)[1].strip() if ',' in expr_line else ""
+                        self.data += f"\t\tKAPI_CONSTRAINT_EXPR({self._format_macro_param(expr)})\n"
+                        break
+
+                self.data += "\tKAPI_CONSTRAINT_END\n"
+                constraint_idx += 1
+
+        # Process signals
+        signal_idx = 0
+        signal_lines = self._get_all_section_lines(sections, 'signal')
+        signal_count = self._get_api_section_value(sections, 'signal-count')
+
+        if signal_count:
+            self.data += f"\n\tKAPI_SIGNAL_COUNT({signal_count})\n"
+        elif len(signal_lines) > 0:
+            self.data += f"\n\tKAPI_SIGNAL_COUNT({len(signal_lines)})\n"
+
+        for line in signal_lines:
+            # Remove this redundant signal count check
+
+            self.data += f"\n\tKAPI_SIGNAL({signal_idx}, 0, {self._format_macro_param(line)}, "
+
+            # Add signal direction
+            signal_dir = self._get_api_section_value(sections, 'signal-direction')
+            if signal_dir:
+                self.data += f"{signal_dir}, "
+            else:
+                self.data += "KAPI_SIGNAL_RECEIVE, "
+
+            # Add signal action
+            signal_action = self._get_api_section_value(sections, 'signal-action')
+            if signal_action:
+                self.data += f"{signal_action})\n"
+            else:
+                self.data += "KAPI_SIGNAL_ACTION_RETURN)\n"
+
+            # Add signal attributes
+            signal_cond = self._get_api_section_value(sections, 'signal-condition')
+            if signal_cond:
+                self.data += f"\t\tKAPI_SIGNAL_CONDITION({self._format_macro_param(signal_cond)})\n"
+
+            signal_desc = self._get_api_section_value(sections, 'signal-desc')
+            if signal_desc:
+                self.data += f"\t\tKAPI_SIGNAL_DESC({self._format_macro_param(signal_desc)})\n"
+
+            signal_error = self._get_api_section_value(sections, 'signal-error')
+            if signal_error:
+                self.data += f"\t\tKAPI_SIGNAL_ERROR({signal_error})\n"
+
+            signal_timing = self._get_api_section_value(sections, 'signal-timing')
+            if signal_timing:
+                self.data += f"\t\tKAPI_SIGNAL_TIMING({signal_timing})\n"
+
+            signal_priority = self._get_api_section_value(sections, 'signal-priority')
+            if signal_priority:
+                self.data += f"\t\tKAPI_SIGNAL_PRIORITY({signal_priority})\n"
+
+            if self._get_api_section_value(sections, 'signal-interruptible'):
+                self.data += "\t\tKAPI_SIGNAL_INTERRUPTIBLE\n"
+
+            signal_state = self._get_api_section_value(sections, 'signal-state-req')
+            if signal_state:
+                self.data += f"\t\tKAPI_SIGNAL_STATE_REQ({signal_state})\n"
+
+            self.data += "\tKAPI_SIGNAL_END\n"
+            signal_idx += 1
+
+        # Process side effects
+        side_effect_lines = self._get_all_section_lines(sections, 'side-effect')
+        effect_count = self._get_api_section_value(sections, 'side-effect-count')
+        if effect_count:
+            self.data += f"\n\tKAPI_SIDE_EFFECT_COUNT({effect_count})\n"
+        elif len(side_effect_lines) > 0:
+            self.data += f"\n\tKAPI_SIDE_EFFECT_COUNT({len(side_effect_lines)})\n"
+
+        # Actually process side effects
+        side_effect_idx = 0
+        for line in side_effect_lines:
+            # Parse: type, target, description[, key=value pairs]
+            # First extract any key=value pairs at the end
+            import re
+
+            # Extract condition=... and reversible=yes
+            condition = None
+            reversible = False
+
+            # Look for condition=... pattern
+            cond_match = re.search(r',\s*condition=([^,]+?)(?:\s*,\s*reversible=yes\s*)?$', line)
+            if cond_match:
+                condition = cond_match.group(1).strip()
+                line = line[:cond_match.start()]  # Remove condition from line
+
+            # Check for reversible=yes
+            if line.endswith(', reversible=yes'):
+                reversible = True
+                line = line[:-len(', reversible=yes')]
+            elif ', reversible=yes,' in line:
+                reversible = True
+                line = line.replace(', reversible=yes,', ',')
+
+            # Now parse the main parts
+            parts = line.split(',', 2)
+            if len(parts) >= 2:
+                effect_type = parts[0].strip()
+                target = parts[1].strip()
+                desc = parts[2].strip() if len(parts) > 2 else ""
+
+                self.data += f"\n\tKAPI_SIDE_EFFECT({side_effect_idx}, {effect_type},\n"
+                self.data += f"\t\t\t {self._format_macro_param(target)},\n"
+                self.data += f"\t\t\t {self._format_macro_param(desc)})\n"
+
+                if condition:
+                    self.data += f"\t\tKAPI_EFFECT_CONDITION({self._format_macro_param(condition)})\n"
+
+                if reversible:
+                    self.data += "\t\tKAPI_EFFECT_REVERSIBLE\n"
+
+                self.data += "\tKAPI_SIDE_EFFECT_END\n"
+                side_effect_idx += 1
+
+        # Process state transitions
+        state_trans_lines = self._get_all_section_lines(sections, 'state-trans')
+        trans_count = self._get_api_section_value(sections, 'state-trans-count')
+        if trans_count:
+            self.data += f"\n\tKAPI_STATE_TRANS_COUNT({trans_count})\n"
+        elif len(state_trans_lines) > 0:
+            self.data += f"\n\tKAPI_STATE_TRANS_COUNT({len(state_trans_lines)})\n"
+
+        state_trans_idx = 0
+        for line in state_trans_lines:
+            parts = line.split(',', 3)
+            if len(parts) >= 3:
+                target = parts[0].strip()
+                from_state = parts[1].strip()
+                to_state = parts[2].strip()
+                desc = parts[3].strip() if len(parts) > 3 else ""
+
+                self.data += f"\n\tKAPI_STATE_TRANS({state_trans_idx}, {self._format_macro_param(target)}, "
+                self.data += f"{self._format_macro_param(from_state)}, {self._format_macro_param(to_state)},\n"
+                self.data += f"\t\t\t {self._format_macro_param(desc)})\n"
+                self.data += "\tKAPI_STATE_TRANS_END\n"
+                state_trans_idx += 1
+
+        # Process capabilities
+        cap_lines = self._get_all_section_lines(sections, 'capability')
+        cap_count = self._get_api_section_value(sections, 'capability-count')
+        if cap_count:
+            self.data += f"\n\tKAPI_CAPABILITY_COUNT({cap_count})\n"
+        elif len(cap_lines) > 0:
+            self.data += f"\n\tKAPI_CAPABILITY_COUNT({len(cap_lines)})\n"
+
+        cap_idx = 0
+        for line in cap_lines:
+            parts = line.split(',', 2)
+            if len(parts) >= 2:
+                cap_name = parts[0].strip()
+                cap_type = parts[1].strip()
+                cap_desc = parts[2].strip() if len(parts) > 2 else cap_name
+
+                self.data += f"\n\tKAPI_CAPABILITY({cap_idx}, {cap_name}, {self._format_macro_param(cap_desc)}, {cap_type})\n"
+
+                # Check for capability attributes
+                cap_allows = self._get_api_section_value(sections, 'capability-allows')
+                if cap_allows:
+                    self.data += f"\t\tKAPI_CAP_ALLOWS({self._format_macro_param(cap_allows)})\n"
+
+                cap_without = self._get_api_section_value(sections, 'capability-without')
+                if cap_without:
+                    self.data += f"\t\tKAPI_CAP_WITHOUT({self._format_macro_param(cap_without)})\n"
+
+                cap_cond = self._get_api_section_value(sections, 'capability-condition')
+                if cap_cond:
+                    self.data += f"\t\tKAPI_CAP_CONDITION({self._format_macro_param(cap_cond)})\n"
+
+                cap_priority = self._get_api_section_value(sections, 'capability-priority')
+                if cap_priority:
+                    self.data += f"\t\tKAPI_CAP_PRIORITY({cap_priority})\n"
+
+                self.data += "\tKAPI_CAPABILITY_END\n"
+                cap_idx += 1
+
+        # Add examples
+        examples = self._get_api_section_value(sections, 'examples')
+        if examples:
+            self.data += f"\n\tKAPI_EXAMPLES({self._format_macro_param(examples)})\n"
+
+        # Add notes
+        notes = self._get_api_section_value(sections, 'notes')
+        if notes:
+            self.data += f"\tKAPI_NOTES({self._format_macro_param(notes)})\n"
+
+        # Process struct specifications
+        struct_types = {}
+        # Find all unique struct types from struct-type and struct-field sections
+        struct_type_lines = self._get_all_section_lines(sections, 'struct-type')
+        for line in struct_type_lines:
+            parts = line.split(',', 1)
+            if len(parts) >= 2:
+                struct_name = parts[1].strip()
+                if struct_name not in struct_types:
+                    struct_types[struct_name] = {'fields': []}
+
+        # Collect struct fields
+        struct_field_lines = self._get_all_section_lines(sections, 'struct-field')
+        current_struct = None
+        if struct_types:
+            # Get the first struct type as the current one
+            current_struct = list(struct_types.keys())[0]
+
+        for line in struct_field_lines:
+            parts = line.split(',', 2)
+            if len(parts) >= 3:
+                field_name = parts[0].strip()
+                field_type = parts[1].strip()
+                field_desc = parts[2].strip()
+                if current_struct and current_struct in struct_types:
+                    struct_types[current_struct]['fields'].append({
+                        'name': field_name,
+                        'type': field_type,
+                        'desc': field_desc
+                    })
+
+        # Generate struct specifications
+        if struct_types:
+            struct_count = len(struct_types)
+            self.data += f"\n\tKAPI_STRUCT_SPEC_COUNT({struct_count})\n"
+
+            struct_idx = 0
+            for struct_name, struct_info in struct_types.items():
+                self.data += f"\n\tKAPI_STRUCT_SPEC({struct_idx}, {self._format_macro_param(struct_name)}, "
+                self.data += f"{self._format_macro_param(f'Structure specification for {struct_name}')})\n"
+
+                # Add field count
+                field_count = len(struct_info['fields'])
+                if field_count > 0:
+                    self.data += f"\t\tKAPI_STRUCT_FIELD_COUNT({field_count})\n"
+
+                # Add fields
+                field_idx = 0
+                for field in struct_info['fields']:
+                    # Map common C types to KAPI types
+                    kapi_type = "KAPI_TYPE_CUSTOM"
+                    if field['type'] in ['__u32', '__u64', '__s32', '__s64', 'u32', 'u64', 's32', 's64']:
+                        if field['type'].startswith('__s') or field['type'].startswith('s'):
+                            kapi_type = "KAPI_TYPE_INT"
+                        else:
+                            kapi_type = "KAPI_TYPE_UINT"
+
+                    self.data += f"\n\t\tKAPI_STRUCT_FIELD({field_idx}, {self._format_macro_param(field['name'])}, "
+                    self.data += f"{kapi_type}, {self._format_macro_param(field['type'])}, "
+                    self.data += f"{self._format_macro_param(field['desc'])})\n"
+
+                    # Add field constraints from other sections
+                    field_range_lines = self._get_all_section_lines(sections, 'struct-field-range')
+                    for range_line in field_range_lines:
+                        if range_line.startswith(field['name'] + ','):
+                            range_parts = range_line.split(',')
+                            if len(range_parts) >= 3:
+                                self.data += f"\t\t\tKAPI_FIELD_CONSTRAINT_RANGE({range_parts[1].strip()}, {range_parts[2].strip()})\n"
+
+                    # Add enum constraints if defined
+                    field_enum_lines = self._get_all_section_lines(sections, 'struct-field-enum')
+                    for enum_line in field_enum_lines:
+                        if enum_line.startswith(field['name'] + ','):
+                            enum_parts = enum_line.split(',', 1)
+                            if len(enum_parts) >= 2:
+                                self.data += f"\t\t\tKAPI_FIELD_CONSTRAINT_ENUM({self._format_macro_param(enum_parts[1].strip())})\n"
+
+                    self.data += "\t\tKAPI_STRUCT_FIELD_END\n"
+                    field_idx += 1
+
+                self.data += "\tKAPI_STRUCT_SPEC_END\n"
+                struct_idx += 1
+
+
+        # Version information is not supported in the current KAPI infrastructure
+        # The 'since' and 'since-version' sections are ignored for now
+
+        self.data += "\nKAPI_END_SPEC;\n\n"
+
+    def out_enum(self, fname, name, args):
+        """Skip enum output for API specs"""
+        pass
+
+    def out_typedef(self, fname, name, args):
+        """Skip typedef output for API specs"""
+        pass
+
+    def out_struct(self, fname, name, args):
+        """Skip struct output for API specs"""
+        pass
+
+    def out_doc(self, fname, name, args):
+        """Skip DOC block output for API specs"""
+        pass
\ No newline at end of file
diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output.py
index 86102e628d917..0c47cffc25e9f 100644
--- a/scripts/lib/kdoc/kdoc_output.py
+++ b/scripts/lib/kdoc/kdoc_output.py
@@ -127,7 +127,10 @@ class OutputFormat:
         warnings = args.get('warnings', [])
 
         for log_msg in warnings:
-            self.config.warning(log_msg)
+            # Skip numeric warnings (line numbers) which are false positives
+            # from parameter-specific sections like "param-constraint: name, value"
+            if not isinstance(log_msg, int):
+                self.config.warning(log_msg)
 
     def check_doc(self, name, args):
         """Check if DOC should be output"""
diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index 062453eefc7a3..4b43023f2a297 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -43,7 +43,25 @@ doc_decl = doc_com + KernRe(r'(\w+)', cache=False)
 # while trying to not match literal block starts like "example::"
 #
 doc_sect = doc_com + \
-            KernRe(r'\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$',
+            KernRe(r'\s*(\@[.\w\-]+|\@\.\.\.|description|context|returns?|notes?|examples?|' +
+                   r'@?api-type|@?api-version|@?param-type|@?param-flags|@?param-constraint|@?param-range|@?param-mask|' +
+                   r'@?param-constraint-type|@?param-size|@?param-alignment|@?param-enum|@?param-validate|' +
+                   r'@?param-size-param|@?param-size-multiplier|' +
+                   r'@?struct-type|@?struct-field|@?struct-field-[a-z\-]+|' +
+                   r'@?validation-group|@?validation-policy|@?validation-flag|@?validation-rule|' +
+                   r'@?error-code|@?error-condition|@?error-count|' +
+                   r'@?capability|@?capability-allows|@?capability-without|@?capability-condition|@?capability-priority|' +
+                   r'@?capability-count|' +
+                   r'@?signal|@?signal-direction|@?signal-action|@?signal-condition|@?signal-desc|@?signal-error|' +
+                   r'@?signal-timing|@?signal-priority|@?signal-interruptible|@?signal-state-req|@?signal-count|' +
+                   r'@?lock|@?lock-type|@?lock-acquired|@?lock-released|@?lock-desc|@?lock-count|' +
+                   r'@?since|@?since-version|' +
+                   r'@?context-flags|@?return-type|@?return-check|@?return-check-type|@?return-success|' +
+                   r'@?long-desc|@?constraint|@?constraint-expr|@?constraint-count|' +
+                   r'@?side-effect|@?side-effect-type|@?side-effect-desc|@?side-effect-condition|' +
+                   r'@?side-effect-reversible|@?side-effect-count|' +
+                   r'@?state-trans|@?state-trans-desc|@?state-trans-count|' +
+                   r'@?param-count|@?kapi-.*)\s*:([^:].*)?$',
                 flags=re.I, cache=False)
 
 doc_content = doc_com_body + KernRe(r'(.*)', cache=False)
@@ -159,7 +177,39 @@ class KernelEntry:
         name = self.section
         contents = self.contents
 
-        if type_param.match(name):
+        # Check if this is an API specification section
+        # These should always be treated as sections, not parameters
+        api_sections = {
+            'api-type', 'api-version', 'param-type', 'param-flags', 'param-constraint',
+            'param-range', 'param-mask', 'param-constraint-type', 'param-size',
+            'param-alignment', 'param-enum', 'param-validate', 'param-size-param',
+            'param-size-multiplier', 'struct-type', 'struct-field', 'struct-field-range',
+            'struct-field-enum', 'struct-field-mask', 'struct-field-policy',
+            'struct-field-version', 'struct-field-flag', 'struct-field-validate',
+            'validation-group', 'validation-policy', 'validation-flag', 'validation-rule',
+            'error-code', 'error-condition', 'error-count',
+            'capability', 'capability-allows', 'capability-without', 'capability-condition',
+            'capability-priority', 'capability-count', 'signal', 'signal-direction',
+            'signal-action', 'signal-condition', 'signal-desc', 'signal-error',
+            'signal-timing', 'signal-priority', 'signal-interruptible', 'signal-state-req',
+            'signal-count', 'lock', 'lock-type', 'lock-acquired', 'lock-released',
+            'lock-desc', 'lock-count', 'since', 'since-version', 'context-flags',
+            'return-type', 'return-check', 'return-check-type', 'return-success',
+            'long-desc', 'constraint', 'constraint-expr', 'constraint-count',
+            'side-effect', 'side-effect-type', 'side-effect-desc', 'side-effect-condition',
+            'side-effect-reversible', 'side-effect-count', 'state-trans',
+            'state-trans-desc', 'state-trans-count', 'param-count',
+            # Also include notes and examples which can appear with or without @
+            'notes', 'note', 'examples', 'example'
+        }
+
+        # Check if name starts with @ and matches kapi-.* pattern
+        is_api_section = (name.lower() in api_sections or
+                         (name.startswith('@') and name[1:].lower() in api_sections) or
+                         (name.lower().startswith('kapi-')) or
+                         (name.lower().startswith('@kapi-')))
+
+        if not is_api_section and type_param.match(name):
             name = type_param.group(1)
 
             self.parameterdescs[name] = contents
-- 
2.39.5