| 1 | #!/usr/bin/env -S gawk -f |
| 2 | # SPDX-License-Identifier: GPL-2.0 |
| 3 | |
| 4 | # Script to check sysctl documentation against source files |
| 5 | # |
| 6 | # Copyright (c) 2020 Stephen Kitt |
| 7 | |
| 8 | # Example invocation: |
| 9 | # scripts/check-sysctl-docs -vtable="kernel" \ |
| 10 | # Documentation/admin-guide/sysctl/kernel.rst \ |
| 11 | # $(git grep -l register_sysctl) |
| 12 | # |
| 13 | # Specify -vdebug=1 to see debugging information |
| 14 | |
| 15 | BEGIN { |
| 16 | if (!table) { |
| 17 | print "Please specify the table to look for using the table variable" > "/dev/stderr" |
| 18 | exit 1 |
| 19 | } |
| 20 | |
| 21 | # Documentation title skiplist |
| 22 | skiplist[0] = "^Documentation for" |
| 23 | skiplist[1] = "Network core options$" |
| 24 | skiplist[2] = "POSIX message queues filesystem$" |
| 25 | skiplist[3] = "Configuration options" |
| 26 | skiplist[4] = ". /proc/sys/fs" |
| 27 | skiplist[5] = "^Introduction$" |
| 28 | skiplist[6] = "^seccomp$" |
| 29 | skiplist[7] = "^pty$" |
| 30 | skiplist[8] = "^firmware_config$" |
| 31 | skiplist[9] = "^random$" |
| 32 | } |
| 33 | |
| 34 | # The following globals are used: |
| 35 | # documented: maps documented entries (each key is an entry) |
| 36 | # entries: maps ctl_table names and procnames to counts (so |
| 37 | # enumerating the subkeys for a given ctl_table lists its |
| 38 | # procnames) |
| 39 | # curtable: the name of the current ctl_table struct |
| 40 | # curentry: the name of the current proc entry (procname when parsing |
| 41 | # a ctl_table, constructed path when parsing a ctl_path) |
| 42 | |
| 43 | |
| 44 | # Remove punctuation from the given value |
| 45 | function trimpunct(value) { |
| 46 | while (value ~ /^["&]/) { |
| 47 | value = substr(value, 2) |
| 48 | } |
| 49 | while (value ~ /[]["&,}]$/) { |
| 50 | value = substr(value, 1, length(value) - 1) |
| 51 | } |
| 52 | return value |
| 53 | } |
| 54 | |
| 55 | # Print the information for the given entry |
| 56 | function printentry(entry) { |
| 57 | seen[entry]++ |
| 58 | printf "* %s from %s", entry, file[entry] |
| 59 | if (documented[entry]) { |
| 60 | printf " (documented)" |
| 61 | } |
| 62 | print "" |
| 63 | } |
| 64 | |
| 65 | |
| 66 | # Stage 1: build the list of documented entries |
| 67 | FNR == NR && /^=+$/ { |
| 68 | for (i in skiplist) { |
| 69 | if (prevline ~ skiplist[i]) { |
| 70 | next |
| 71 | } |
| 72 | } |
| 73 | |
| 74 | # The previous line is a section title, parse it |
| 75 | $0 = prevline |
| 76 | if (debug) print "Parsing " $0 |
| 77 | inbrackets = 0 |
| 78 | for (i = 1; i <= NF; i++) { |
| 79 | if (length($i) == 0) { |
| 80 | continue |
| 81 | } |
| 82 | if (!inbrackets && substr($i, 1, 1) == "(") { |
| 83 | inbrackets = 1 |
| 84 | } |
| 85 | if (!inbrackets) { |
| 86 | token = trimpunct($i) |
| 87 | if (length(token) > 0 && token != "and") { |
| 88 | if (debug) print trimpunct($i) |
| 89 | documented[trimpunct($i)]++ |
| 90 | } |
| 91 | } |
| 92 | if (inbrackets && substr($i, length($i), 1) == ")") { |
| 93 | inbrackets = 0 |
| 94 | } |
| 95 | } |
| 96 | } |
| 97 | |
| 98 | FNR == NR { |
| 99 | prevline = $0 |
| 100 | next |
| 101 | } |
| 102 | |
| 103 | |
| 104 | # Stage 2: process each file and find all sysctl tables |
| 105 | BEGINFILE { |
| 106 | delete entries |
| 107 | curtable = "" |
| 108 | curentry = "" |
| 109 | delete vars |
| 110 | if (debug) print "Processing file " FILENAME |
| 111 | } |
| 112 | |
| 113 | /^static( const)? struct ctl_table/ { |
| 114 | match($0, /static( const)? struct ctl_table ([^][]+)/, tables) |
| 115 | curtable = tables[2] |
| 116 | if (debug) print "Processing table " curtable |
| 117 | } |
| 118 | |
| 119 | /^};$/ { |
| 120 | curtable = "" |
| 121 | curentry = "" |
| 122 | delete vars |
| 123 | } |
| 124 | |
| 125 | curtable && /\.procname[\t ]*=[\t ]*".+"/ { |
| 126 | match($0, /.procname[\t ]*=[\t ]*"([^"]+)"/, names) |
| 127 | curentry = names[1] |
| 128 | if (debug) print "Adding entry " curentry " to table " curtable |
| 129 | entries[curtable][curentry]++ |
| 130 | file[curentry] = FILENAME |
| 131 | } |
| 132 | |
| 133 | curtable && /UCOUNT_ENTRY.*/ { |
| 134 | match($0, /UCOUNT_ENTRY\("([^"]+)"\)/, names) |
| 135 | curentry = names[1] |
| 136 | if (debug) print "Adding entry " curentry " to table " curtable |
| 137 | entries[curtable][curentry]++ |
| 138 | file[curentry] = FILENAME |
| 139 | } |
| 140 | |
| 141 | /register_sysctl.*/ { |
| 142 | match($0, /register_sysctl(|_init|_sz)\("([^"]+)" *, *([^,)]+)/, tables) |
| 143 | if (debug) print "Registering table " tables[3] " at " tables[2] |
| 144 | if (tables[2] == table) { |
| 145 | for (entry in entries[tables[3]]) { |
| 146 | printentry(entry) |
| 147 | } |
| 148 | } |
| 149 | } |
| 150 | |
| 151 | /kmemdup.*/ { |
| 152 | match($0, /([^ \t]+) *= *kmemdup\(([^,]+) *,/, names) |
| 153 | if (debug) print "Found variable " names[1] " for table " names[2] |
| 154 | if (names[2] in entries) { |
| 155 | vars[names[1]] = names[2] |
| 156 | } |
| 157 | } |
| 158 | |
| 159 | /__register_sysctl_table.*/ { |
| 160 | match($0, /__register_sysctl_table\([^,]+, *"([^"]+)" *, *([^,]+)/, tables) |
| 161 | if (debug) print "Registering variable table " tables[2] " at " tables[1] |
| 162 | if (tables[1] == table && tables[2] in vars) { |
| 163 | for (entry in entries[vars[tables[2]]]) { |
| 164 | printentry(entry) |
| 165 | } |
| 166 | } |
| 167 | } |
| 168 | |
| 169 | END { |
| 170 | for (entry in documented) { |
| 171 | if (!seen[entry]) |
| 172 | print "No implementation for " entry |
| 173 | } |
| 174 | } |