Some drivers have multiple doc files sharing one code directory (e.g., igb, igc, e1000 variants). Others have doc files for VF/DCF variants (e.g., ice_dcf, ixgbe_vf).
Extend driver_code_dir() to strip variant suffixes and map driver names to their shared code directories. Build a cache mapping each code directory to its associated doc files. Add docs_for_code() to retrieve all doc names for a given code directory. Add items_not_in() to compute set difference between two lists. Use it in check_rte_flow() to compare doc vs code items: - items documented but not in code are always reported, - items in code but not documented in any doc for the code directory are reported, avoiding false positives when multiple docs share the same code. Also rename doc files to match their code directory names. Signed-off-by: David Marchand <[email protected]> --- Changes since v2: - introduced logic earlier in the series, - added comments and implemented for rte_flow checks, --- MAINTAINERS | 2 +- devtools/check-doc-vs-code.sh | 109 +++++++++++++++--- .../features/{afpacket.ini => af_packet.ini} | 2 +- .../features/{cxgbevf.ini => cxgbe_vf.ini} | 2 +- 4 files changed, 98 insertions(+), 17 deletions(-) rename doc/guides/nics/features/{afpacket.ini => af_packet.ini} (70%) rename doc/guides/nics/features/{cxgbevf.ini => cxgbe_vf.ini} (90%) diff --git a/MAINTAINERS b/MAINTAINERS index 1720cff62e..e05bea2f0c 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -679,7 +679,7 @@ F: examples/bond/ Linux AF_PACKET M: Stephen Hemminger <[email protected]> F: drivers/net/af_packet/ -F: doc/guides/nics/features/afpacket.ini +F: doc/guides/nics/features/af_packet.ini F: app/test/test_pmd_af_packet.c Linux AF_XDP diff --git a/devtools/check-doc-vs-code.sh b/devtools/check-doc-vs-code.sh index e141fe9938..7afc18d153 100755 --- a/devtools/check-doc-vs-code.sh +++ b/devtools/check-doc-vs-code.sh @@ -36,35 +36,86 @@ has_file_change() # <pattern> changed_files | grep -q "$1" } +net_driver_from_path() # <path> +{ + sed -rn ' + s,.*drivers/net/intel/([^/]*)/.*,\1,p; t + s,.*drivers/net/([^./]*)/.*,\1,p; t + s,.*doc/guides/nics/features/([^./]*).*,\1,p' | + grep -v '^default$' +} + changed_net_drivers() { [ -n "$drivers" ] || drivers=$(changed_files | - sed -rn ' - s,^drivers/net/intel/([^/]*).*,\1,p; t - s,^drivers/net/([^/]*).*,\1,p; t - s,^doc/guides/nics/features/([^.]*).*,\1,p' | + net_driver_from_path | sort -u) echo "$drivers" } all_net_drivers() { - find $rootdir/drivers/net -name meson.build | - sed -rn ' - s,.*drivers/net/intel/([^/]*).*,\1,p; t - s,.*drivers/net/([^/]*).*,\1,p' | + { + find $rootdir/drivers/net -name meson.build + ls $rootdir/doc/guides/nics/features/*.ini + } | + net_driver_from_path | sort -u } # give back a driver directory for a doc/driver name driver_code_dir() # <driver_name> { - if [ -d $rootdir/drivers/net/intel/$1 ]; then - echo "$rootdir/drivers/net/intel/$1" - else - echo "$rootdir/drivers/net/$1" - fi + drv=$(echo "$1" | sed -r 's/_(dcf|vec|vf)$//') + case $drv in + enetc|enetc4) + echo "$rootdir/drivers/net/enetc" ;; + igb|igc|e1000) + echo "$rootdir/drivers/net/intel/e1000" ;; + *) + if [ -d $rootdir/drivers/net/intel/$drv ]; then + echo "$rootdir/drivers/net/intel/$drv" + else + echo "$rootdir/drivers/net/$drv" + fi ;; + esac +} + +# create a cache of the mapping between a driver code directory and associated driver docs +# format of this cache is: +# ^,$drv1_directory: $drv1_doc_name1 $drv1_doc_name2,$drv2_directory: $drv2_doc_name1,...,$ +doc_code_map="," +for d in $rootdir/doc/guides/nics/features/*.ini; do + drv=$(basename "$d" .ini) + [ "$drv" != 'default' ] || continue + code=$(driver_code_dir $drv) + case $doc_code_map in + *,$code:*) + before=${doc_code_map%,$code:*} + after=${doc_code_map#*,$code:} + drvs=${after%%,*} + rest=${after#*,} + doc_code_map="$before,$code:$drvs $drv,$rest" ;; + *) + doc_code_map="$doc_code_map$code: $drv," ;; + esac +done + +# extract all doc names from the cache created above +docs_for_code() # <code_dir> +{ + tmp=${doc_code_map#*,$1:} + echo ${tmp%%,*} +} + +# output items from first list that are not in second list +items_not_in() # <list1> <list2> +{ + { + [ -n "$1" ] && echo "$1" + [ -n "$2" ] && { echo "$2"; echo "$2"; } + } | sort | uniq -u } check_rte_flow() # <driver> @@ -73,7 +124,37 @@ check_rte_flow() # <driver> doc=$rootdir/doc/guides/nics/features/$1.ini [ -d $code ] || return 0 [ -f $doc ] || return 0 - report=$($selfdir/parse-flow-support.sh $code $doc) + code_support=$($selfdir/parse-flow-support.sh $code) + report=$( + for category in item action; do + section="rte_flow ${category}s]" + code_items=$(echo "$code_support" | sed -n "/$section/,/]/p" | + sed '/]/d' | # ignore section title + sed 's, *=.*,,' | # keep only item name + sed '/^$/d' | # remove empty lines + sort -u) + doc_items=$(sed -n "/$section/,/]/p" "$doc" | + sed '/]/d' | # ignore section title + sed 's, *=.*,,' | # keep only item name + sed '/^$/d' | # remove empty lines + sort -u) + { + # items documented but not in code + items_not_in "$doc_items" "$code_items" + # items in code but not documented in any doc for the code directory + all_doc_items=$( + for drv in $(docs_for_code $code); do + d=$rootdir/doc/guides/nics/features/$drv.ini + sed -n "/$section/,/]/p" "$d" | + sed '/]/d' | # ignore section title + sed 's, *=.*,,' | # keep only item name + sed '/^$/d' # remove empty lines + done | sort -u + ) + items_not_in "$code_items" "$all_doc_items" + } | sed "s,^,$category ," # prefix with category name + done + ) if [ -n "$report" ]; then error "rte_flow doc out of sync for $1" echo "$report" | sed 's,^,\t,' diff --git a/doc/guides/nics/features/afpacket.ini b/doc/guides/nics/features/af_packet.ini similarity index 70% rename from doc/guides/nics/features/afpacket.ini rename to doc/guides/nics/features/af_packet.ini index bc669dfb8a..b1cbc54aca 100644 --- a/doc/guides/nics/features/afpacket.ini +++ b/doc/guides/nics/features/af_packet.ini @@ -1,5 +1,5 @@ ; -; Supported features of the 'afpacket' network poll mode driver. +; Supported features of the 'af_packet' network poll mode driver. ; ; Refer to default.ini for the full list of available PMD features. ; diff --git a/doc/guides/nics/features/cxgbevf.ini b/doc/guides/nics/features/cxgbe_vf.ini similarity index 90% rename from doc/guides/nics/features/cxgbevf.ini rename to doc/guides/nics/features/cxgbe_vf.ini index a921cda6b1..b77b202272 100644 --- a/doc/guides/nics/features/cxgbevf.ini +++ b/doc/guides/nics/features/cxgbe_vf.ini @@ -1,5 +1,5 @@ ; -; Supported features of the 'cxgbevf' network poll mode driver. +; Supported features of the 'cxgbe_vf' network poll mode driver. ; ; Refer to default.ini for the full list of available PMD features. ; -- 2.54.0
