devtools: check flow API doc tables

The script check-doc-vs-code.sh may be used to add
some automatic checks of the doc.

If run without any argument, a complete check is done.
The optional argument is a git history reference point
to check faster only what has changed since this commit.

In this commit, the only check is for rte_flow tables,
achieved through the script parse-flow-support.sh.
If run without a .ini reference, it prints rte_flow tables.
Note: detected features are marked with the value Y,
while the real .ini file could have special values like I.
The script allow parsing exceptions (exclude or include),
like for bnxt code which lists unsupported items and actions.

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
v6 changes:
	- fix redundant drivers
	- ignore indirect action
	- prefix misses with a category (item or action)

diff --git a/MAINTAINERS b/MAINTAINERS
index 38e2848..5877a16 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -77,6 +77,7 @@ Developers and Maintainers Tools
 M: Thomas Monjalon <thomas@monjalon.net>
 F: MAINTAINERS
 F: devtools/build-dict.sh
+F: devtools/check-doc-vs-code.sh
 F: devtools/check-dup-includes.sh
 F: devtools/check-maintainers.sh
 F: devtools/check-forbidden-tokens.awk
@@ -87,6 +88,7 @@ F: devtools/checkpatches.sh
 F: devtools/get-maintainer.sh
 F: devtools/git-log-fixes.sh
 F: devtools/load-devel-config
+F: devtools/parse-flow-support.sh
 F: devtools/update-patches.py
 F: devtools/words-case.txt
 F: license/

diff --git a/devtools/check-doc-vs-code.sh b/devtools/check-doc-vs-code.sh
new file mode 100755 (executable)
index 0000000..c58c239
--- /dev/null
+++ b/devtools/check-doc-vs-code.sh
@@ -0,0 +1,84 @@
+#! /bin/sh -e
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2021 Mellanox Technologies, Ltd
+
+# Check whether doc & code are in sync.
+# Optional argument: check only what changed since a commit.
+trusted_commit=$1 # example: origin/main
+
+selfdir=$(dirname $(readlink -f $0))
+rootdir=$(readlink -f $selfdir/..)
+
+# speed up by ignoring Unicode details
+export LC_COLLATE=C
+
+result=0
+error() # <message>
+{
+       echo "$*"
+       result=$(($result + 1))
+}
+
+changed_files()
+{
+       [ -n "$files" ] ||
+               files=$(git diff-tree --name-only -r $trusted_commit..)
+       echo "$files"
+}
+
+has_code_change() # <pattern>
+{
+       test -n "$(git log --format='%h' -S"$1" $trusted_commit..)"
+}
+
+has_file_change() # <pattern>
+{
+       changed_files | grep -q "$1"
+}
+
+changed_net_drivers()
+{
+       net_paths='drivers/net/|doc/guides/nics/features/'
+       [ -n "$drivers" ] ||
+               drivers=$(changed_files |
+                       sed -rn "s,^($net_paths)([^./]*).*,\2,p" |
+                       sort -u)
+       echo "$drivers"
+}
+
+all_net_drivers()
+{
+       find $rootdir/drivers/net -mindepth 1 -maxdepth 1 -type d |
+       sed 's,.*/,,' |
+       sort
+}
+
+check_rte_flow() # <driver>
+{
+       code=$rootdir/drivers/net/$1
+       doc=$rootdir/doc/guides/nics/features/$1.ini
+       [ -d $code ] || return 0
+       [ -f $doc ] || return 0
+       report=$($selfdir/parse-flow-support.sh $code $doc)
+       if [ -n "$report" ]; then
+               error "rte_flow doc out of sync for $1"
+               echo "$report" | sed 's,^,\t,'
+       fi
+}
+
+if [ -z "$trusted_commit" ]; then
+       # check all
+       for driver in $(all_net_drivers); do
+               check_rte_flow $driver
+       done
+       exit $result
+fi
+
+# find what changed and check
+if has_code_change 'RTE_FLOW_.*_TYPE_' ||
+               has_file_change 'doc/guides/nics/features'; then
+       for driver in $(changed_net_drivers); do
+               check_rte_flow $driver
+       done
+fi
+exit $result

diff --git a/devtools/parse-flow-support.sh b/devtools/parse-flow-support.sh
new file mode 100755 (executable)
index 0000000..aeed76e
--- /dev/null
+++ b/devtools/parse-flow-support.sh
@@ -0,0 +1,78 @@
+#! /bin/sh -e
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2021 Mellanox Technologies, Ltd
+
+# Parse rte_flow support of a driver directory,
+# and optionally show difference with a doc file in .ini format.
+
+dir=$1 # drivers/net/foo
+ref=$2 # doc/guides/nics/features/foo.ini
+
+if [ -z "$dir" ]; then
+       echo "directory argument is required" >&2
+       exit 1
+fi
+
+# sorting order
+export LC_COLLATE=C
+
+# exclude exceptions
+exclude() # <pattern>
+{
+       case $(basename $dir) in
+               bnxt)
+                       filter=$(sed -n "/$1/{N;/TYPE_NOT_SUPPORTED/P;}" \
+                               $dir/tf_ulp/ulp_template_db{,_tbl}.c |
+                               grep -wo "$1[[:alnum:]_]*" | sort -u |
+                               tr '\n' '|' | sed 's,.$,\n,')
+                       grep -vE "$filter";;
+               *) cat
+       esac
+}
+
+# include exceptions
+include() # <pattern>
+{
+       case $(basename $dir) in
+       esac
+}
+
+# generate INI section
+list() # <title> <pattern>
+{
+       echo "[$1]"
+       git grep -who "$2[[:alnum:]_]*" $dir |
+       (exclude $2; include $2) | sort -u |
+       awk 'sub(/'$2'/, "") {printf "%-20s = Y\n", tolower($0)}'
+}
+
+rte_flow_support() # <category>
+{
+       title="rte_flow $1s"
+       pattern=$(echo "RTE_FLOW_$1_TYPE_" | awk '{print toupper($0)}')
+       list "$title" "$pattern" | grep -vwE 'void|indirect|end'
+}
+
+if [ -z "$ref" ]; then # generate full tables
+       rte_flow_support item
+       echo
+       rte_flow_support action
+       exit 0
+fi
+
+# compare with reference input
+rte_flow_compare() # <category>
+{
+       section="rte_flow $1s]"
+       {
+               rte_flow_support $1
+               sed -n "/$section/,/]/p" "$ref" | sed '/^$/d'
+       } |
+       sed '/]/d' | # ignore section title
+       sed 's, *=.*,,' | # ignore value (better in doc than generated one)
+       sort | uniq -u | # show differences
+       sed "s,^,$1 ," # prefix with category name
+}
+
+rte_flow_compare item
+rte_flow_compare action