Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | /* |
2 | * docproc is a simple preprocessor for the template files | |
3 | * used as placeholders for the kernel internal documentation. | |
4 | * docproc is used for documentation-frontend and | |
5 | * dependency-generator. | |
6 | * The two usages have in common that they require | |
7 | * some knowledge of the .tmpl syntax, therefore they | |
8 | * are kept together. | |
9 | * | |
10 | * documentation-frontend | |
11 | * Scans the template file and call kernel-doc for | |
12 | * all occurrences of ![EIF]file | |
6dd16f44 RD |
13 | * Beforehand each referenced file is scanned for |
14 | * any symbols that are exported via these macros: | |
15 | * EXPORT_SYMBOL(), EXPORT_SYMBOL_GPL(), & | |
16 | * EXPORT_SYMBOL_GPL_FUTURE() | |
1da177e4 LT |
17 | * This is used to create proper -function and |
18 | * -nofunction arguments in calls to kernel-doc. | |
19 | * Usage: docproc doc file.tmpl | |
20 | * | |
21 | * dependency-generator: | |
22 | * Scans the template file and list all files | |
23 | * referenced in a format recognized by make. | |
24 | * Usage: docproc depend file.tmpl | |
25 | * Writes dependency information to stdout | |
26 | * in the following format: | |
27 | * file.tmpl src.c src2.c | |
28 | * The filenames are obtained from the following constructs: | |
29 | * !Efilename | |
30 | * !Ifilename | |
31 | * !Dfilename | |
32 | * !Ffilename | |
33 | * | |
34 | */ | |
35 | ||
36 | #include <stdio.h> | |
37 | #include <stdlib.h> | |
38 | #include <string.h> | |
39 | #include <ctype.h> | |
40 | #include <unistd.h> | |
41 | #include <limits.h> | |
42 | #include <sys/types.h> | |
43 | #include <sys/wait.h> | |
44 | ||
45 | /* exitstatus is used to keep track of any failing calls to kernel-doc, | |
46 | * but execution continues. */ | |
47 | int exitstatus = 0; | |
48 | ||
49 | typedef void DFL(char *); | |
50 | DFL *defaultline; | |
51 | ||
52 | typedef void FILEONLY(char * file); | |
53 | FILEONLY *internalfunctions; | |
54 | FILEONLY *externalfunctions; | |
55 | FILEONLY *symbolsonly; | |
56 | ||
48b9d03c | 57 | typedef void FILELINE(char * file, char * line); |
1da177e4 LT |
58 | FILELINE * singlefunctions; |
59 | FILELINE * entity_system; | |
60 | ||
61 | #define MAXLINESZ 2048 | |
62 | #define MAXFILES 250 | |
63 | #define KERNELDOCPATH "scripts/" | |
64 | #define KERNELDOC "kernel-doc" | |
65 | #define DOCBOOK "-docbook" | |
66 | #define FUNCTION "-function" | |
67 | #define NOFUNCTION "-nofunction" | |
2e95972c | 68 | #define NODOCSECTIONS "-no-doc-sections" |
1da177e4 | 69 | |
bb13be51 RL |
70 | char *srctree; |
71 | ||
1da177e4 LT |
72 | void usage (void) |
73 | { | |
74 | fprintf(stderr, "Usage: docproc {doc|depend} file\n"); | |
75 | fprintf(stderr, "Input is read from file.tmpl. Output is sent to stdout\n"); | |
76 | fprintf(stderr, "doc: frontend when generating kernel documentation\n"); | |
77 | fprintf(stderr, "depend: generate list of files referenced within file\n"); | |
bb13be51 | 78 | fprintf(stderr, "Environment variable SRCTREE: absolute path to kernel source tree.\n"); |
1da177e4 LT |
79 | } |
80 | ||
81 | /* | |
6dd16f44 | 82 | * Execute kernel-doc with parameters given in svec |
1da177e4 LT |
83 | */ |
84 | void exec_kernel_doc(char **svec) | |
85 | { | |
86 | pid_t pid; | |
87 | int ret; | |
88 | char real_filename[PATH_MAX + 1]; | |
89 | /* Make sure output generated so far are flushed */ | |
90 | fflush(stdout); | |
6dd16f44 | 91 | switch (pid=fork()) { |
1da177e4 LT |
92 | case -1: |
93 | perror("fork"); | |
94 | exit(1); | |
95 | case 0: | |
96 | memset(real_filename, 0, sizeof(real_filename)); | |
bb13be51 | 97 | strncat(real_filename, srctree, PATH_MAX); |
1da177e4 LT |
98 | strncat(real_filename, KERNELDOCPATH KERNELDOC, |
99 | PATH_MAX - strlen(real_filename)); | |
100 | execvp(real_filename, svec); | |
101 | fprintf(stderr, "exec "); | |
102 | perror(real_filename); | |
103 | exit(1); | |
104 | default: | |
105 | waitpid(pid, &ret ,0); | |
106 | } | |
107 | if (WIFEXITED(ret)) | |
108 | exitstatus |= WEXITSTATUS(ret); | |
109 | else | |
110 | exitstatus = 0xff; | |
111 | } | |
112 | ||
113 | /* Types used to create list of all exported symbols in a number of files */ | |
114 | struct symbols | |
115 | { | |
116 | char *name; | |
117 | }; | |
118 | ||
119 | struct symfile | |
120 | { | |
121 | char *filename; | |
122 | struct symbols *symbollist; | |
123 | int symbolcnt; | |
124 | }; | |
125 | ||
126 | struct symfile symfilelist[MAXFILES]; | |
127 | int symfilecnt = 0; | |
128 | ||
129 | void add_new_symbol(struct symfile *sym, char * symname) | |
130 | { | |
131 | sym->symbollist = | |
132 | realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *)); | |
133 | sym->symbollist[sym->symbolcnt++].name = strdup(symname); | |
134 | } | |
135 | ||
136 | /* Add a filename to the list */ | |
137 | struct symfile * add_new_file(char * filename) | |
138 | { | |
139 | symfilelist[symfilecnt++].filename = strdup(filename); | |
140 | return &symfilelist[symfilecnt - 1]; | |
141 | } | |
6dd16f44 | 142 | |
1da177e4 LT |
143 | /* Check if file already are present in the list */ |
144 | struct symfile * filename_exist(char * filename) | |
145 | { | |
146 | int i; | |
147 | for (i=0; i < symfilecnt; i++) | |
148 | if (strcmp(symfilelist[i].filename, filename) == 0) | |
149 | return &symfilelist[i]; | |
150 | return NULL; | |
151 | } | |
152 | ||
153 | /* | |
154 | * List all files referenced within the template file. | |
155 | * Files are separated by tabs. | |
156 | */ | |
157 | void adddep(char * file) { printf("\t%s", file); } | |
48b9d03c | 158 | void adddep2(char * file, char * line) { line = line; adddep(file); } |
1da177e4 | 159 | void noaction(char * line) { line = line; } |
48b9d03c | 160 | void noaction2(char * file, char * line) { file = file; line = line; } |
1da177e4 LT |
161 | |
162 | /* Echo the line without further action */ | |
163 | void printline(char * line) { printf("%s", line); } | |
164 | ||
165 | /* | |
6dd16f44 RD |
166 | * Find all symbols in filename that are exported with EXPORT_SYMBOL & |
167 | * EXPORT_SYMBOL_GPL (& EXPORT_SYMBOL_GPL_FUTURE implicitly). | |
1da177e4 LT |
168 | * All symbols located are stored in symfilelist. |
169 | */ | |
170 | void find_export_symbols(char * filename) | |
171 | { | |
172 | FILE * fp; | |
173 | struct symfile *sym; | |
174 | char line[MAXLINESZ]; | |
175 | if (filename_exist(filename) == NULL) { | |
176 | char real_filename[PATH_MAX + 1]; | |
177 | memset(real_filename, 0, sizeof(real_filename)); | |
bb13be51 | 178 | strncat(real_filename, srctree, PATH_MAX); |
1da177e4 LT |
179 | strncat(real_filename, filename, |
180 | PATH_MAX - strlen(real_filename)); | |
181 | sym = add_new_file(filename); | |
182 | fp = fopen(real_filename, "r"); | |
183 | if (fp == NULL) | |
184 | { | |
185 | fprintf(stderr, "docproc: "); | |
186 | perror(real_filename); | |
074a5dde | 187 | exit(1); |
1da177e4 | 188 | } |
6dd16f44 | 189 | while (fgets(line, MAXLINESZ, fp)) { |
48b9d03c M |
190 | char *p; |
191 | char *e; | |
6dd16f44 RD |
192 | if (((p = strstr(line, "EXPORT_SYMBOL_GPL")) != NULL) || |
193 | ((p = strstr(line, "EXPORT_SYMBOL")) != NULL)) { | |
1da177e4 LT |
194 | /* Skip EXPORT_SYMBOL{_GPL} */ |
195 | while (isalnum(*p) || *p == '_') | |
196 | p++; | |
6dd16f44 | 197 | /* Remove parentheses & additional whitespace */ |
1da177e4 LT |
198 | while (isspace(*p)) |
199 | p++; | |
200 | if (*p != '(') | |
201 | continue; /* Syntax error? */ | |
202 | else | |
203 | p++; | |
204 | while (isspace(*p)) | |
205 | p++; | |
206 | e = p; | |
207 | while (isalnum(*e) || *e == '_') | |
208 | e++; | |
209 | *e = '\0'; | |
210 | add_new_symbol(sym, p); | |
211 | } | |
212 | } | |
213 | fclose(fp); | |
214 | } | |
215 | } | |
216 | ||
217 | /* | |
218 | * Document all external or internal functions in a file. | |
219 | * Call kernel-doc with following parameters: | |
220 | * kernel-doc -docbook -nofunction function_name1 filename | |
6dd16f44 | 221 | * Function names are obtained from all the src files |
1da177e4 LT |
222 | * by find_export_symbols. |
223 | * intfunc uses -nofunction | |
224 | * extfunc uses -function | |
225 | */ | |
226 | void docfunctions(char * filename, char * type) | |
227 | { | |
228 | int i,j; | |
229 | int symcnt = 0; | |
230 | int idx = 0; | |
231 | char **vec; | |
232 | ||
233 | for (i=0; i <= symfilecnt; i++) | |
234 | symcnt += symfilelist[i].symbolcnt; | |
2e95972c | 235 | vec = malloc((2 + 2 * symcnt + 3) * sizeof(char *)); |
1da177e4 LT |
236 | if (vec == NULL) { |
237 | perror("docproc: "); | |
238 | exit(1); | |
239 | } | |
240 | vec[idx++] = KERNELDOC; | |
241 | vec[idx++] = DOCBOOK; | |
2e95972c | 242 | vec[idx++] = NODOCSECTIONS; |
1da177e4 LT |
243 | for (i=0; i < symfilecnt; i++) { |
244 | struct symfile * sym = &symfilelist[i]; | |
245 | for (j=0; j < sym->symbolcnt; j++) { | |
246 | vec[idx++] = type; | |
247 | vec[idx++] = sym->symbollist[j].name; | |
248 | } | |
249 | } | |
250 | vec[idx++] = filename; | |
251 | vec[idx] = NULL; | |
252 | printf("<!-- %s -->\n", filename); | |
253 | exec_kernel_doc(vec); | |
254 | fflush(stdout); | |
255 | free(vec); | |
256 | } | |
257 | void intfunc(char * filename) { docfunctions(filename, NOFUNCTION); } | |
258 | void extfunc(char * filename) { docfunctions(filename, FUNCTION); } | |
259 | ||
260 | /* | |
c6120938 | 261 | * Document specific function(s) in a file. |
1da177e4 LT |
262 | * Call kernel-doc with the following parameters: |
263 | * kernel-doc -docbook -function function1 [-function function2] | |
264 | */ | |
48b9d03c | 265 | void singfunc(char * filename, char * line) |
1da177e4 LT |
266 | { |
267 | char *vec[200]; /* Enough for specific functions */ | |
268 | int i, idx = 0; | |
269 | int startofsym = 1; | |
270 | vec[idx++] = KERNELDOC; | |
271 | vec[idx++] = DOCBOOK; | |
272 | ||
6dd16f44 | 273 | /* Split line up in individual parameters preceded by FUNCTION */ |
1da177e4 LT |
274 | for (i=0; line[i]; i++) { |
275 | if (isspace(line[i])) { | |
276 | line[i] = '\0'; | |
277 | startofsym = 1; | |
278 | continue; | |
279 | } | |
280 | if (startofsym) { | |
281 | startofsym = 0; | |
282 | vec[idx++] = FUNCTION; | |
283 | vec[idx++] = &line[i]; | |
284 | } | |
285 | } | |
286 | vec[idx++] = filename; | |
287 | vec[idx] = NULL; | |
288 | exec_kernel_doc(vec); | |
289 | } | |
290 | ||
291 | /* | |
292 | * Parse file, calling action specific functions for: | |
293 | * 1) Lines containing !E | |
294 | * 2) Lines containing !I | |
295 | * 3) Lines containing !D | |
296 | * 4) Lines containing !F | |
297 | * 5) Default lines - lines not matching the above | |
298 | */ | |
299 | void parse_file(FILE *infile) | |
300 | { | |
301 | char line[MAXLINESZ]; | |
48b9d03c | 302 | char * s; |
6dd16f44 | 303 | while (fgets(line, MAXLINESZ, infile)) { |
1da177e4 LT |
304 | if (line[0] == '!') { |
305 | s = line + 2; | |
306 | switch (line[1]) { | |
307 | case 'E': | |
308 | while (*s && !isspace(*s)) s++; | |
309 | *s = '\0'; | |
310 | externalfunctions(line+2); | |
311 | break; | |
312 | case 'I': | |
313 | while (*s && !isspace(*s)) s++; | |
314 | *s = '\0'; | |
315 | internalfunctions(line+2); | |
316 | break; | |
317 | case 'D': | |
318 | while (*s && !isspace(*s)) s++; | |
319 | *s = '\0'; | |
320 | symbolsonly(line+2); | |
321 | break; | |
322 | case 'F': | |
323 | /* filename */ | |
324 | while (*s && !isspace(*s)) s++; | |
325 | *s++ = '\0'; | |
326 | /* function names */ | |
327 | while (isspace(*s)) | |
328 | s++; | |
329 | singlefunctions(line +2, s); | |
330 | break; | |
331 | default: | |
332 | defaultline(line); | |
333 | } | |
334 | } | |
335 | else { | |
336 | defaultline(line); | |
337 | } | |
338 | } | |
339 | fflush(stdout); | |
340 | } | |
341 | ||
342 | ||
343 | int main(int argc, char *argv[]) | |
344 | { | |
345 | FILE * infile; | |
bb13be51 RL |
346 | |
347 | srctree = getenv("SRCTREE"); | |
348 | if (!srctree) | |
349 | srctree = getcwd(NULL, 0); | |
1da177e4 LT |
350 | if (argc != 3) { |
351 | usage(); | |
352 | exit(1); | |
353 | } | |
354 | /* Open file, exit on error */ | |
355 | infile = fopen(argv[2], "r"); | |
356 | if (infile == NULL) { | |
357 | fprintf(stderr, "docproc: "); | |
358 | perror(argv[2]); | |
359 | exit(2); | |
360 | } | |
361 | ||
362 | if (strcmp("doc", argv[1]) == 0) | |
363 | { | |
364 | /* Need to do this in two passes. | |
365 | * First pass is used to collect all symbols exported | |
6dd16f44 | 366 | * in the various files; |
1da177e4 | 367 | * Second pass generate the documentation. |
6dd16f44 | 368 | * This is required because some functions are declared |
1da177e4 LT |
369 | * and exported in different files :-(( |
370 | */ | |
371 | /* Collect symbols */ | |
372 | defaultline = noaction; | |
373 | internalfunctions = find_export_symbols; | |
374 | externalfunctions = find_export_symbols; | |
375 | symbolsonly = find_export_symbols; | |
376 | singlefunctions = noaction2; | |
377 | parse_file(infile); | |
378 | ||
379 | /* Rewind to start from beginning of file again */ | |
380 | fseek(infile, 0, SEEK_SET); | |
381 | defaultline = printline; | |
382 | internalfunctions = intfunc; | |
383 | externalfunctions = extfunc; | |
384 | symbolsonly = printline; | |
385 | singlefunctions = singfunc; | |
386 | ||
387 | parse_file(infile); | |
388 | } | |
389 | else if (strcmp("depend", argv[1]) == 0) | |
390 | { | |
391 | /* Create first part of dependency chain | |
392 | * file.tmpl */ | |
393 | printf("%s\t", argv[2]); | |
394 | defaultline = noaction; | |
395 | internalfunctions = adddep; | |
396 | externalfunctions = adddep; | |
397 | symbolsonly = adddep; | |
398 | singlefunctions = adddep2; | |
399 | parse_file(infile); | |
400 | printf("\n"); | |
401 | } | |
402 | else | |
403 | { | |
404 | fprintf(stderr, "Unknown option: %s\n", argv[1]); | |
405 | exit(1); | |
406 | } | |
407 | fclose(infile); | |
408 | fflush(stdout); | |
409 | return exitstatus; | |
410 | } |