xref: /linux/scripts/check-sysctl-docs (revision be0aef10dca87a644affb087f01728386c19903a) 
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
15BEGIN {
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
45function 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
56function 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
67FNR == 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
98FNR == NR {
99    prevline = $0
100    next
101}
102
103
104# Stage 2: process each file and find all sysctl tables
105BEGINFILE {
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
125curtable && /\.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/register_sysctl.*/ {
134    match($0, /register_sysctl(|_init|_sz)\("([^"]+)" *, *([^,)]+)/, tables)
135    if (debug) print "Registering table " tables[3] " at " tables[2]
136    if (tables[2] == table) {
137        for (entry in entries[tables[3]]) {
138            printentry(entry)
139        }
140    }
141}
142
143/kmemdup.*/ {
144    match($0, /([^ \t]+) *= *kmemdup\(([^,]+) *,/, names)
145    if (debug) print "Found variable " names[1] " for table " names[2]
146    if (names[2] in entries) {
147        vars[names[1]] = names[2]
148    }
149}
150
151/__register_sysctl_table.*/ {
152    match($0, /__register_sysctl_table\([^,]+, *"([^"]+)" *, *([^,]+)/, tables)
153    if (debug) print "Registering variable table " tables[2] " at " tables[1]
154    if (tables[1] == table && tables[2] in vars) {
155        for (entry in entries[vars[tables[2]]]) {
156            printentry(entry)
157        }
158    }
159}
160
161END {
162    for (entry in documented) {
163	if (!seen[entry]) {
164	    print "No implementation for " entry
165	}
166    }
167}
168