drm: ensure drm headers are self-contained and pass kernel-doc

Ensure drm headers build, are self-contained, have header guards, and
have no kernel-doc warnings, when CONFIG_DRM_HEADER_TEST=y.

The mechanism follows similar patters used in i915, xe, and usr/include.

To cover include/drm, we need to recurse there using the top level
Kbuild and the new include/Kbuild files.

v4: check for CONFIG_WERROR in addition to CONFIG_DRM_WERROR

v3: adapt to upstream build changes

v2: make DRM_HEADER_TEST depend on DRM

Suggested-by: Daniel Vetter <daniel@ffwll.ch>
Cc: David Airlie <airlied@gmail.com>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Maxime Ripard <mripard@kernel.org>
Cc: Thomas Zimmermann <tzimmermann@suse.de>
Cc: Masahiro Yamada <masahiroy@kernel.org>
Acked-by: Thomas Zimmermann <tzimmermann@suse.de>
Acked-by: Simona Vetter <simona.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/d8ad1c6d707f38a55987f616cb9650aef30b84e1.1737556766.git.jani.nikula@intel.com
Signed-off-by: Jani Nikula <jani.nikula@intel.com>

diff --git a/Kbuild b/Kbuild
index 464b34a08f51ef9d2ae12e6902c92690b5dfa03b..f327ca86990cca0c209d1c615019e6f47c9861ab 100644 (file)
--- a/Kbuild
+++ b/Kbuild
@@ -97,3 +97,4 @@ obj-$(CONFIG_SAMPLES) += samples/
 obj-$(CONFIG_NET)      += net/
 obj-y                  += virt/
 obj-y                  += $(ARCH_DRIVERS)
+obj-$(CONFIG_DRM_HEADER_TEST)  += include/

diff --git a/drivers/gpu/drm/Kconfig b/drivers/gpu/drm/Kconfig
index fbef3f471bd0e5101699cf576542f7350bea3982..f9b3ebf63fa97ea17ab85efa4275e7b1ff6d4010 100644 (file)
--- a/drivers/gpu/drm/Kconfig
+++ b/drivers/gpu/drm/Kconfig
@@ -494,6 +494,17 @@ config DRM_WERROR
 
          If in doubt, say N.
 
+config DRM_HEADER_TEST
+       bool "Ensure DRM headers are self-contained and pass kernel-doc"
+       depends on DRM && EXPERT
+       default n
+       help
+         Ensure the DRM subsystem headers both under drivers/gpu/drm and
+         include/drm compile, are self-contained, have header guards, and have
+         no kernel-doc warnings.
+
+         If in doubt, say N.
+
 endif
 
 # Separate option because drm_panel_orientation_quirks.c is shared with fbdev

diff --git a/drivers/gpu/drm/Makefile b/drivers/gpu/drm/Makefile
index 85af94bb907d6cdbad7078e2667426e479b1069f..42901f877bf256765829b5fe25bf7844202338cb 100644 (file)
--- a/drivers/gpu/drm/Makefile
+++ b/drivers/gpu/drm/Makefile
@@ -222,3 +222,21 @@ obj-y                      += solomon/
 obj-$(CONFIG_DRM_SPRD) += sprd/
 obj-$(CONFIG_DRM_LOONGSON) += loongson/
 obj-$(CONFIG_DRM_POWERVR) += imagination/
+
+# Ensure drm headers are self-contained and pass kernel-doc
+hdrtest-files := \
+       $(shell cd $(src) && find . -maxdepth 1 -name 'drm_*.h') \
+       $(shell cd $(src) && find display lib -name '*.h')
+
+always-$(CONFIG_DRM_HEADER_TEST) += \
+       $(patsubst %.h,%.hdrtest, $(hdrtest-files))
+
+# Include the header twice to detect missing include guard.
+quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@)
+      cmd_hdrtest = \
+               $(CC) $(c_flags) -fsyntax-only -x c /dev/null -include $< -include $<; \
+               $(srctree)/scripts/kernel-doc -none $(if $(CONFIG_WERROR)$(CONFIG_DRM_WERROR),-Werror) $<; \
+               touch $@
+
+$(obj)/%.hdrtest: $(src)/%.h FORCE
+       $(call if_changed_dep,hdrtest)

diff --git a/include/Kbuild b/include/Kbuild
new file mode 100644 (file)
index 0000000..5e76a59
--- /dev/null
+++ b/include/Kbuild
@@ -0,0 +1 @@
+obj-$(CONFIG_DRM_HEADER_TEST)  += drm/

diff --git a/include/drm/Makefile b/include/drm/Makefile
new file mode 100644 (file)
index 0000000..a7bd15d
--- /dev/null
+++ b/include/drm/Makefile
@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: GPL-2.0
+
+# Ensure drm headers are self-contained and pass kernel-doc
+hdrtest-files := \
+       $(shell cd $(src) && find * -name '*.h' 2>/dev/null)
+
+always-$(CONFIG_DRM_HEADER_TEST) += \
+       $(patsubst %.h,%.hdrtest, $(hdrtest-files))
+
+# Include the header twice to detect missing include guard.
+quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@)
+      cmd_hdrtest = \
+               $(CC) $(c_flags) -fsyntax-only -x c /dev/null -include $< -include $<; \
+               $(srctree)/scripts/kernel-doc -none $(if $(CONFIG_WERROR)$(CONFIG_DRM_WERROR),-Werror) $<; \
+               touch $@
+
+$(obj)/%.hdrtest: $(src)/%.h FORCE
+       $(call if_changed_dep,hdrtest)