7eae53419a4825a2b99c4287afea0061695e9a72
[linux-2.6.git] / scripts / basic / docproc.c
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
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()
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
57 typedef void FILELINE(char * file, char * line);
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"
68 #define NODOCSECTIONS "-no-doc-sections"
69
70 char *srctree;
71
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");
78         fprintf(stderr, "Environment variable SRCTREE: absolute path to kernel source tree.\n");
79 }
80
81 /*
82  * Execute kernel-doc with parameters given in svec
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);
91         switch (pid=fork()) {
92                 case -1:
93                         perror("fork");
94                         exit(1);
95                 case  0:
96                         memset(real_filename, 0, sizeof(real_filename));
97                         strncat(real_filename, srctree, PATH_MAX);
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 }
142
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); }
158 void adddep2(char * file, char * line)     { line = line; adddep(file); }
159 void noaction(char * line)                 { line = line; }
160 void noaction2(char * file, char * line)   { file = file; line = line; }
161
162 /* Echo the line without further action */
163 void printline(char * line)               { printf("%s", line); }
164
165 /*
166  * Find all symbols in filename that are exported with EXPORT_SYMBOL &
167  * EXPORT_SYMBOL_GPL (& EXPORT_SYMBOL_GPL_FUTURE implicitly).
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));
178                 strncat(real_filename, srctree, PATH_MAX);
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);
187                         exit(1);
188                 }
189                 while (fgets(line, MAXLINESZ, fp)) {
190                         char *p;
191                         char *e;
192                         if (((p = strstr(line, "EXPORT_SYMBOL_GPL")) != NULL) ||
193                             ((p = strstr(line, "EXPORT_SYMBOL")) != NULL)) {
194                                 /* Skip EXPORT_SYMBOL{_GPL} */
195                                 while (isalnum(*p) || *p == '_')
196                                         p++;
197                                 /* Remove parentheses & additional whitespace */
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
221  * Function names are obtained from all the src files
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;
235         vec = malloc((2 + 2 * symcnt + 3) * sizeof(char *));
236         if (vec == NULL) {
237                 perror("docproc: ");
238                 exit(1);
239         }
240         vec[idx++] = KERNELDOC;
241         vec[idx++] = DOCBOOK;
242         vec[idx++] = NODOCSECTIONS;
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 /*
261  * Document specific function(s) in a file.
262  * Call kernel-doc with the following parameters:
263  * kernel-doc -docbook -function function1 [-function function2]
264  */
265 void singfunc(char * filename, char * line)
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
273         /* Split line up in individual parameters preceded by FUNCTION */
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];
302         char * s;
303         while (fgets(line, MAXLINESZ, infile)) {
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;
346
347         srctree = getenv("SRCTREE");
348         if (!srctree)
349                 srctree = getcwd(NULL, 0);
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
366                  * in the various files;
367                  * Second pass generate the documentation.
368                  * This is required because some functions are declared
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 }