Quelle  check-sysctl-docs   Sprache: HTML

#!/usr/bin/env -S gawk -f
# SPDX-License-Identifier: GPL-2.0

# Script to check sysctl documentation against source files
#
# Copyright (c) 2020 Stephen Kitt

# Example invocation:
# scripts/check-sysctl-docs -vtable="kernel" \
#  Documentation/admin-guide/sysctl/kernel.rst \
#  $(git grep -l register_sysctl)
#
# Specify -vdebug=1 to see debugging information

BEGIN {
 if (!table) {
 print "Please specify the table to look for using the table variable" > "/dev/stderr"
 exit 1
 }

 # Documentation title skiplist
 skiplist[0] = "^Documentation for"
 skiplist[1] = "Network core options$"
 skiplist[2] = "POSIX message queues filesystem$"
 skiplist[3] = "Configuration options"
 skiplist[4] = ". /proc/sys/fs"
 skiplist[5] = "^Introduction$"
 skiplist[6] = "^seccomp$"
 skiplist[7] = "^pty$"
 skiplist[8] = "^firmware_config$"
 skiplist[9] = "^random$"
}

# The following globals are used:
# documented: maps documented entries (each key is an entry)
# entries: maps ctl_table names and procnames to counts (so
#          enumerating the subkeys for a given ctl_table lists its
#          procnames)
# curtable: the name of the current ctl_table struct
# curentry: the name of the current proc entry (procname when parsing
#           a ctl_table, constructed path when parsing a ctl_path)


# Remove punctuation from the given value
function trimpunct(value) {
 while (value ~ /^["&]/) {
  value = substr(value, 2)
 }
 while (value ~ /[]["&,}]$/) {
  value = substr(value, 1, length(value) - 1)
 }
 return value
}

# Print the information for the given entry
function printentry(entry) {
 seen[entry]++
 printf "* %s from %s", entry, file[entry]
 if (documented[entry]) {
  printf " (documented)"
 }
 print ""
}


# Stage 1: build the list of documented entries
FNR == NR && /^=+$/ {
 for (i in skiplist) {
  if (prevline ~ skiplist[i]) {
   next
  }
 }

 # The previous line is a section title, parse it
 $0 = prevline
 if (debug) print "Parsing " $0
 inbrackets = 0
 for (i = 1; i <= NF; i++) {
  if (length($i) == 0) {
   continue
  }
  if (!inbrackets && substr($i, 1, 1) == "(") {
   inbrackets = 1
  }
  if (!inbrackets) {
   token = trimpunct($i)
   if (length(token) > 0 && token != "and") {
    if (debug) print trimpunct($i)
     documented[trimpunct($i)]++
   }
  }
  if (inbrackets && substr($i, length($i), 1) == ")") {
   inbrackets = 0
  }
 }
}

FNR == NR {
 prevline = $0
 next
}


# Stage 2: process each file and find all sysctl tables
BEGINFILE {
 delete entries
 curtable = ""
 curentry = ""
 delete vars
 if (debug) print "Processing file " FILENAME
}

/^static( const)? struct ctl_table/ {
 match($0, /static( const)? struct ctl_table ([^][]+)/, tables)
 curtable = tables[2]
 if (debug) print "Processing table " curtable
}

/^};$/ {
 curtable = ""
 curentry = ""
 delete vars
}

curtable && /\.procname[\t ]*=[\t ]*".+"/ {
 match($0, /.procname[\t ]*=[\t ]*"([^"]+)"/, names)
 curentry = names[1]
 if (debug) print "Adding entry " curentry " to table " curtable
 entries[curtable][curentry]++
 file[curentry] = FILENAME
}

curtable && /UCOUNT_ENTRY.*/ {
 match($0, /UCOUNT_ENTRY\("([^"]+)"\)/, names)
 curentry = names[1]
 if (debug) print "Adding entry " curentry " to table " curtable
 entries[curtable][curentry]++
 file[curentry] = FILENAME
}

/register_sysctl.*/ {
 match($0, /register_sysctl(|_init|_sz)\("([^"]+)" *, *([^,)]+)/, tables)
 if (debug) print "Registering table " tables[3] " at " tables[2]
 if (tables[2] == table) {
  for (entry in entries[tables[3]]) {
   printentry(entry)
  }
 }
}

/kmemdup.*/ {
 match($0, /([^ \t]+) *= *kmemdup\(([^,]+) *,/, names)
 if (debug) print "Found variable " names[1] " for table " names[2]
 if (names[2] in entries) {
  vars[names[1]] = names[2]
 }
}

/__register_sysctl_table.*/ {
 match($0, /__register_sysctl_table\([^,]+, *"([^"]+)" *, *([^,]+)/, tables)
 if (debug) print "Registering variable table " tables[2] " at " tables[1]
 if (tables[1] == table && tables[2] in vars) {
  for (entry in entries[vars[tables[2]]]) {
   printentry(entry)
  }
 }
}

END {
 for (entry in documented) {
  if (!seen[entry])
   print "No implementation for " entry
 }
}