From f45f72c9a4c4d243c9b82490c9d06ca72cd27323 Mon Sep 17 00:00:00 2001 From: Peter Bigot Date: Tue, 21 Jul 2020 15:04:14 -0500 Subject: [PATCH] doc: development_process: document that CI style checks can fail The CI style checking solution can produce false positives when it's given code that it mis-parses, or that follows conventions it doesn't allow. Document a couple examples, and explicitly note that maintainers should override the -1 vote if they're encountered. For those following along in the commit history: static uint8_t __aligned(PAGE_SIZE) page_pool[PAGE_SIZE * POOL_PAGES]; checkpatch sees "uint8_t __aligned(PAGE_SIZE)" and infers a prototype for a function "__aligned" that takes an unnamed parameter of type "PAGE_SIZE". So it adds "PAGE_SIZE" as a known type name. IOPCTL_Type *base = config->base; This is common in driver code where the vendor HAL allows typedefs for structure types. checkpatch was designed for an environment with limited use of typedefs; "struct IPCTL_Type" would have been handled properly. Signed-off-by: Peter Bigot --- doc/development_process/dev_env_and_tools.rst | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/doc/development_process/dev_env_and_tools.rst b/doc/development_process/dev_env_and_tools.rst index 133bde27130..08008ffa378 100644 --- a/doc/development_process/dev_env_and_tools.rst +++ b/doc/development_process/dev_env_and_tools.rst @@ -210,7 +210,7 @@ Developers are expected to fix issues and rework their patches and submit again. The CI infrastructure currently runs the following tests: -- Run ''checkpatch'' for code style issues (can vote -1 on errors) +- Run ''checkpatch'' for code style issues (can vote -1 on errors; see note) - Gitlint: Git commit style based on project requirements - License Check: Check for conflicting licenses - Run ''sanitycheck'' script @@ -220,6 +220,25 @@ The CI infrastructure currently runs the following tests: - Verify documentation builds correctly. +.. note:: + + ''checkpatch'' is a Perl script that uses regular expressions to + extract information that requires a C language parser to process + accurately. As such it sometimes issues false positives. Known + cases include constructs like:: + + static uint8_t __aligned(PAGE_SIZE) page_pool[PAGE_SIZE * POOL_PAGES]; + IOPCTL_Type *base = config->base; + + Both lines produce a diagnostic regarding spaces around the ``*`` + operator: the first is misidentifed as a pointer type declaration + that would be correct as ``PAGE_SIZE *POOL_PAGES`` while the second + is misidentified as a multiplication expression that would be correct + as ``IOPCTL_Type * base``. + + Maintainers can override the -1 in cases where the CI infrastructure + gets the wrong answer. + .. _gh_labels: