[master] b76e25bd3 Chère coccinelle, ma vie devient si cruelle

[Nils Goroll]

commit b76e25bd38a29ea2dee26cf5f4595c7a84f3cc39
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Tue Jul 11 20:40:54 2023 +0200

    Chère coccinelle, ma vie devient si cruelle

diff --git a/tools/coccinelle/README.rst b/tools/coccinelle/README.rst
index 8b24b0583..a611aed76 100644
--- a/tools/coccinelle/README.rst
+++ b/tools/coccinelle/README.rst
@@ -1,8 +1,14 @@
 ..
 	Copyright (c) 2019-2022 Varnish Software AS
+	Copyright 2023 UPLEX - Nils Goroll Systemoptimierung
 	SPDX-License-Identifier: BSD-2-Clause
 	See LICENSE file for full text of license
 
+THE EASY PART
+=============
+
+.. _coccinelle: http://coccinelle.lip6.fr/
+
 This directory contains `coccinelle`_ semantic patches to facilitate code
 maintenance.
 
@@ -30,4 +36,64 @@ should not need again, but want to retain for reference.
 Do not commit any ``libvgz`` changes, as this code is manually kept in
 sync with upstream.
 
-.. _coccinelle: http://coccinelle.lip6.fr/
+THE HARD PART
+=============
+
+*or: a word of warning.*
+
+Coccinelle does not like our way of using macros for code generation,
+but it will silently ignore anything it does not understand, so it
+will not cause any harm.
+
+Except when it does. Ruin your day.
+
+Because you wonder why code which clearly should match on a semantic
+patch does not.
+
+Take this example, which motivated this section to be written::
+
+  @@
+  type T;
+  T e1, e2;
+  @@
+
+  - vmin_t(T, e1, e2)
+  + vmin(e1, e2)
+
+simple as can be: For a type ``T``, replace ``vmin_t(T, ..., ...)`` for
+expressions which are also of type ``T``.
+
+Yet, why does it not change this code ...
+
+::
+
+   static int
+   vcl_acl_cmp(const struct acl_e *ae1, const struct acl_e *ae2)
+   {
+     // ...
+     m = vmin_t(unsigned, ae1->mask, ae2->mask);
+
+when it does in fact change similar places.
+
+Reason: It could not parse the ``struct acl_e`` declaration, so it
+could not determine that the ``mask`` member is in fact of type
+``unsigned``.
+
+Check for parse errors
+----------------------
+
+In such cases, *do* check for parse errors in the affected file using
+``spatch --parse-c``. Here's a one-liner to check the whole tree::
+
+  for file in $(find . -name \*.c) ; do
+    if spatch --macro-file tools/coccinelle/vdef.h \
+       -I include/ -I bin/varnishd/  --parse-c $file 2>&1 |
+       grep -C 5 -E '^BAD' ; then
+         echo ; echo $file
+    fi
+  done
+
+There are many cases for which no obvious workaround exists yet, but
+some have been added to ``tools/coccinelle/vdef.h``.
+
+Good lug with the ladybug.
diff --git a/tools/coccinelle/vdef.h b/tools/coccinelle/vdef.h
index ba0248a30..3562dce21 100644
--- a/tools/coccinelle/vdef.h
+++ b/tools/coccinelle/vdef.h
@@ -1,3 +1,8 @@
+/*
+ * IF you wonder about the stupid contents of this file,
+ * DO read tools/coccinelle/README.rst
+ */
+
 /* vdef.h */
 #define v_printflike_(f,a)
 #define v_deprecated_
@@ -11,3 +16,14 @@
 
 /* vcc_if.h */
 #define VPFX(a)	vmod_##a
+
+/* vqueue.h */
+#define VTAILQ_ENTRY(x) unsigned
+#define VSTAILQ_ENTRY(x) unsigned
+#define VTAILQ_HEAD(x, y) unsigned
+#define VSTAILQ_HEAD(x, y) unsigned
+#define VRBT_ENTRY(x) unsigned
+#define VRBT_HEAD(x, y) unsigned
+
+/* lib/libvcc/vcc_vmod.c */
+#define STANZA_TBL