Version:  2.0.40 2.2.26 2.4.37 3.13 3.14 3.15 3.16 3.17 3.18 3.19 4.0 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10

Linux/scripts/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  *              !Pfilename
 34  *
 35  */
 36 
 37 #define _GNU_SOURCE
 38 #include <stdio.h>
 39 #include <stdlib.h>
 40 #include <string.h>
 41 #include <ctype.h>
 42 #include <unistd.h>
 43 #include <limits.h>
 44 #include <errno.h>
 45 #include <getopt.h>
 46 #include <sys/types.h>
 47 #include <sys/wait.h>
 48 #include <time.h>
 49 
 50 /* exitstatus is used to keep track of any failing calls to kernel-doc,
 51  * but execution continues. */
 52 int exitstatus = 0;
 53 
 54 typedef void DFL(char *);
 55 DFL *defaultline;
 56 
 57 typedef void FILEONLY(char * file);
 58 FILEONLY *internalfunctions;
 59 FILEONLY *externalfunctions;
 60 FILEONLY *symbolsonly;
 61 FILEONLY *findall;
 62 
 63 typedef void FILELINE(char * file, char * line);
 64 FILELINE * singlefunctions;
 65 FILELINE * entity_system;
 66 FILELINE * docsection;
 67 
 68 #define MAXLINESZ     2048
 69 #define MAXFILES      250
 70 #define KERNELDOCPATH "scripts/"
 71 #define KERNELDOC     "kernel-doc"
 72 #define DOCBOOK       "-docbook"
 73 #define RST           "-rst"
 74 #define LIST          "-list"
 75 #define FUNCTION      "-function"
 76 #define NOFUNCTION    "-nofunction"
 77 #define NODOCSECTIONS "-no-doc-sections"
 78 #define SHOWNOTFOUND  "-show-not-found"
 79 
 80 enum file_format {
 81         FORMAT_AUTO,
 82         FORMAT_DOCBOOK,
 83         FORMAT_RST,
 84 };
 85 
 86 static enum file_format file_format = FORMAT_AUTO;
 87 
 88 #define KERNELDOC_FORMAT        (file_format == FORMAT_RST ? RST : DOCBOOK)
 89 
 90 static char *srctree, *kernsrctree;
 91 
 92 static char **all_list = NULL;
 93 static int all_list_len = 0;
 94 
 95 static void consume_symbol(const char *sym)
 96 {
 97         int i;
 98 
 99         for (i = 0; i < all_list_len; i++) {
100                 if (!all_list[i])
101                         continue;
102                 if (strcmp(sym, all_list[i]))
103                         continue;
104                 all_list[i] = NULL;
105                 break;
106         }
107 }
108 
109 static void usage (void)
110 {
111         fprintf(stderr, "Usage: docproc [{--docbook|--rst}] {doc|depend} file\n");
112         fprintf(stderr, "Input is read from file.tmpl. Output is sent to stdout\n");
113         fprintf(stderr, "doc: frontend when generating kernel documentation\n");
114         fprintf(stderr, "depend: generate list of files referenced within file\n");
115         fprintf(stderr, "Environment variable SRCTREE: absolute path to sources.\n");
116         fprintf(stderr, "                     KBUILD_SRC: absolute path to kernel source tree.\n");
117 }
118 
119 /*
120  * Execute kernel-doc with parameters given in svec
121  */
122 static void exec_kernel_doc(char **svec)
123 {
124         pid_t pid;
125         int ret;
126         char real_filename[PATH_MAX + 1];
127         /* Make sure output generated so far are flushed */
128         fflush(stdout);
129         switch (pid=fork()) {
130                 case -1:
131                         perror("fork");
132                         exit(1);
133                 case  0:
134                         memset(real_filename, 0, sizeof(real_filename));
135                         strncat(real_filename, kernsrctree, PATH_MAX);
136                         strncat(real_filename, "/" KERNELDOCPATH KERNELDOC,
137                                         PATH_MAX - strlen(real_filename));
138                         execvp(real_filename, svec);
139                         fprintf(stderr, "exec ");
140                         perror(real_filename);
141                         exit(1);
142                 default:
143                         waitpid(pid, &ret ,0);
144         }
145         if (WIFEXITED(ret))
146                 exitstatus |= WEXITSTATUS(ret);
147         else
148                 exitstatus = 0xff;
149 }
150 
151 /* Types used to create list of all exported symbols in a number of files */
152 struct symbols
153 {
154         char *name;
155 };
156 
157 struct symfile
158 {
159         char *filename;
160         struct symbols *symbollist;
161         int symbolcnt;
162 };
163 
164 struct symfile symfilelist[MAXFILES];
165 int symfilecnt = 0;
166 
167 static void add_new_symbol(struct symfile *sym, char * symname)
168 {
169         sym->symbollist =
170           realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *));
171         sym->symbollist[sym->symbolcnt++].name = strdup(symname);
172 }
173 
174 /* Add a filename to the list */
175 static struct symfile * add_new_file(char * filename)
176 {
177         symfilelist[symfilecnt++].filename = strdup(filename);
178         return &symfilelist[symfilecnt - 1];
179 }
180 
181 /* Check if file already are present in the list */
182 static struct symfile * filename_exist(char * filename)
183 {
184         int i;
185         for (i=0; i < symfilecnt; i++)
186                 if (strcmp(symfilelist[i].filename, filename) == 0)
187                         return &symfilelist[i];
188         return NULL;
189 }
190 
191 /*
192  * List all files referenced within the template file.
193  * Files are separated by tabs.
194  */
195 static void adddep(char * file)            { printf("\t%s", file); }
196 static void adddep2(char * file, char * line)     { line = line; adddep(file); }
197 static void noaction(char * line)                  { line = line; }
198 static void noaction2(char * file, char * line)   { file = file; line = line; }
199 
200 /* Echo the line without further action */
201 static void printline(char * line)               { printf("%s", line); }
202 
203 /*
204  * Find all symbols in filename that are exported with EXPORT_SYMBOL &
205  * EXPORT_SYMBOL_GPL (& EXPORT_SYMBOL_GPL_FUTURE implicitly).
206  * All symbols located are stored in symfilelist.
207  */
208 static void find_export_symbols(char * filename)
209 {
210         FILE * fp;
211         struct symfile *sym;
212         char line[MAXLINESZ];
213         if (filename_exist(filename) == NULL) {
214                 char real_filename[PATH_MAX + 1];
215                 memset(real_filename, 0, sizeof(real_filename));
216                 strncat(real_filename, srctree, PATH_MAX);
217                 strncat(real_filename, "/", PATH_MAX - strlen(real_filename));
218                 strncat(real_filename, filename,
219                                 PATH_MAX - strlen(real_filename));
220                 sym = add_new_file(filename);
221                 fp = fopen(real_filename, "r");
222                 if (fp == NULL) {
223                         fprintf(stderr, "docproc: ");
224                         perror(real_filename);
225                         exit(1);
226                 }
227                 while (fgets(line, MAXLINESZ, fp)) {
228                         char *p;
229                         char *e;
230                         if (((p = strstr(line, "EXPORT_SYMBOL_GPL")) != NULL) ||
231                             ((p = strstr(line, "EXPORT_SYMBOL")) != NULL)) {
232                                 /* Skip EXPORT_SYMBOL{_GPL} */
233                                 while (isalnum(*p) || *p == '_')
234                                         p++;
235                                 /* Remove parentheses & additional whitespace */
236                                 while (isspace(*p))
237                                         p++;
238                                 if (*p != '(')
239                                         continue; /* Syntax error? */
240                                 else
241                                         p++;
242                                 while (isspace(*p))
243                                         p++;
244                                 e = p;
245                                 while (isalnum(*e) || *e == '_')
246                                         e++;
247                                 *e = '\0';
248                                 add_new_symbol(sym, p);
249                         }
250                 }
251                 fclose(fp);
252         }
253 }
254 
255 /*
256  * Document all external or internal functions in a file.
257  * Call kernel-doc with following parameters:
258  * kernel-doc [-docbook|-rst] -nofunction function_name1 filename
259  * Function names are obtained from all the src files
260  * by find_export_symbols.
261  * intfunc uses -nofunction
262  * extfunc uses -function
263  */
264 static void docfunctions(char * filename, char * type)
265 {
266         int i,j;
267         int symcnt = 0;
268         int idx = 0;
269         char **vec;
270 
271         for (i=0; i <= symfilecnt; i++)
272                 symcnt += symfilelist[i].symbolcnt;
273         vec = malloc((2 + 2 * symcnt + 3) * sizeof(char *));
274         if (vec == NULL) {
275                 perror("docproc: ");
276                 exit(1);
277         }
278         vec[idx++] = KERNELDOC;
279         vec[idx++] = KERNELDOC_FORMAT;
280         vec[idx++] = NODOCSECTIONS;
281         for (i=0; i < symfilecnt; i++) {
282                 struct symfile * sym = &symfilelist[i];
283                 for (j=0; j < sym->symbolcnt; j++) {
284                         vec[idx++]     = type;
285                         consume_symbol(sym->symbollist[j].name);
286                         vec[idx++] = sym->symbollist[j].name;
287                 }
288         }
289         vec[idx++]     = filename;
290         vec[idx] = NULL;
291         if (file_format == FORMAT_RST)
292                 printf(".. %s\n", filename);
293         else
294                 printf("<!-- %s -->\n", filename);
295         exec_kernel_doc(vec);
296         fflush(stdout);
297         free(vec);
298 }
299 static void intfunc(char * filename) {  docfunctions(filename, NOFUNCTION); }
300 static void extfunc(char * filename) { docfunctions(filename, FUNCTION);   }
301 
302 /*
303  * Document specific function(s) in a file.
304  * Call kernel-doc with the following parameters:
305  * kernel-doc -docbook -function function1 [-function function2]
306  */
307 static void singfunc(char * filename, char * line)
308 {
309         char *vec[200]; /* Enough for specific functions */
310         int i, idx = 0;
311         int startofsym = 1;
312         vec[idx++] = KERNELDOC;
313         vec[idx++] = KERNELDOC_FORMAT;
314         vec[idx++] = SHOWNOTFOUND;
315 
316         /* Split line up in individual parameters preceded by FUNCTION */
317         for (i=0; line[i]; i++) {
318                 if (isspace(line[i])) {
319                         line[i] = '\0';
320                         startofsym = 1;
321                         continue;
322                 }
323                 if (startofsym) {
324                         startofsym = 0;
325                         vec[idx++] = FUNCTION;
326                         vec[idx++] = &line[i];
327                 }
328         }
329         for (i = 0; i < idx; i++) {
330                 if (strcmp(vec[i], FUNCTION))
331                         continue;
332                 consume_symbol(vec[i + 1]);
333         }
334         vec[idx++] = filename;
335         vec[idx] = NULL;
336         exec_kernel_doc(vec);
337 }
338 
339 /*
340  * Insert specific documentation section from a file.
341  * Call kernel-doc with the following parameters:
342  * kernel-doc -docbook -function "doc section" filename
343  */
344 static void docsect(char *filename, char *line)
345 {
346         /* kerneldoc -docbook -show-not-found -function "section" file NULL */
347         char *vec[7];
348         char *s;
349 
350         for (s = line; *s; s++)
351                 if (*s == '\n')
352                         *s = '\0';
353 
354         if (asprintf(&s, "DOC: %s", line) < 0) {
355                 perror("asprintf");
356                 exit(1);
357         }
358         consume_symbol(s);
359         free(s);
360 
361         vec[0] = KERNELDOC;
362         vec[1] = KERNELDOC_FORMAT;
363         vec[2] = SHOWNOTFOUND;
364         vec[3] = FUNCTION;
365         vec[4] = line;
366         vec[5] = filename;
367         vec[6] = NULL;
368         exec_kernel_doc(vec);
369 }
370 
371 static void find_all_symbols(char *filename)
372 {
373         char *vec[4]; /* kerneldoc -list file NULL */
374         pid_t pid;
375         int ret, i, count, start;
376         char real_filename[PATH_MAX + 1];
377         int pipefd[2];
378         char *data, *str;
379         size_t data_len = 0;
380 
381         vec[0] = KERNELDOC;
382         vec[1] = LIST;
383         vec[2] = filename;
384         vec[3] = NULL;
385 
386         if (pipe(pipefd)) {
387                 perror("pipe");
388                 exit(1);
389         }
390 
391         switch (pid=fork()) {
392                 case -1:
393                         perror("fork");
394                         exit(1);
395                 case  0:
396                         close(pipefd[0]);
397                         dup2(pipefd[1], 1);
398                         memset(real_filename, 0, sizeof(real_filename));
399                         strncat(real_filename, kernsrctree, PATH_MAX);
400                         strncat(real_filename, "/" KERNELDOCPATH KERNELDOC,
401                                         PATH_MAX - strlen(real_filename));
402                         execvp(real_filename, vec);
403                         fprintf(stderr, "exec ");
404                         perror(real_filename);
405                         exit(1);
406                 default:
407                         close(pipefd[1]);
408                         data = malloc(4096);
409                         do {
410                                 while ((ret = read(pipefd[0],
411                                                    data + data_len,
412                                                    4096)) > 0) {
413                                         data_len += ret;
414                                         data = realloc(data, data_len + 4096);
415                                 }
416                         } while (ret == -EAGAIN);
417                         if (ret != 0) {
418                                 perror("read");
419                                 exit(1);
420                         }
421                         waitpid(pid, &ret ,0);
422         }
423         if (WIFEXITED(ret))
424                 exitstatus |= WEXITSTATUS(ret);
425         else
426                 exitstatus = 0xff;
427 
428         count = 0;
429         /* poor man's strtok, but with counting */
430         for (i = 0; i < data_len; i++) {
431                 if (data[i] == '\n') {
432                         count++;
433                         data[i] = '\0';
434                 }
435         }
436         start = all_list_len;
437         all_list_len += count;
438         all_list = realloc(all_list, sizeof(char *) * all_list_len);
439         str = data;
440         for (i = 0; i < data_len && start != all_list_len; i++) {
441                 if (data[i] == '\0') {
442                         all_list[start] = str;
443                         str = data + i + 1;
444                         start++;
445                 }
446         }
447 }
448 
449 /*
450  * Terminate s at first space, if any. If there was a space, return pointer to
451  * the character after that. Otherwise, return pointer to the terminating NUL.
452  */
453 static char *chomp(char *s)
454 {
455         while (*s && !isspace(*s))
456                 s++;
457 
458         if (*s)
459                 *s++ = '\0';
460 
461         return s;
462 }
463 
464 /* Return pointer to directive content, or NULL if not a directive. */
465 static char *is_directive(char *line)
466 {
467         if (file_format == FORMAT_DOCBOOK && line[0] == '!')
468                 return line + 1;
469         else if (file_format == FORMAT_RST && !strncmp(line, ".. !", 4))
470                 return line + 4;
471 
472         return NULL;
473 }
474 
475 /*
476  * Parse file, calling action specific functions for:
477  * 1) Lines containing !E
478  * 2) Lines containing !I
479  * 3) Lines containing !D
480  * 4) Lines containing !F
481  * 5) Lines containing !P
482  * 6) Lines containing !C
483  * 7) Default lines - lines not matching the above
484  */
485 static void parse_file(FILE *infile)
486 {
487         char line[MAXLINESZ];
488         char *p, *s;
489         while (fgets(line, MAXLINESZ, infile)) {
490                 p = is_directive(line);
491                 if (!p) {
492                         defaultline(line);
493                         continue;
494                 }
495 
496                 switch (*p++) {
497                 case 'E':
498                         chomp(p);
499                         externalfunctions(p);
500                         break;
501                 case 'I':
502                         chomp(p);
503                         internalfunctions(p);
504                         break;
505                 case 'D':
506                         chomp(p);
507                         symbolsonly(p);
508                         break;
509                 case 'F':
510                         /* filename */
511                         s = chomp(p);
512                         /* function names */
513                         while (isspace(*s))
514                                 s++;
515                         singlefunctions(p, s);
516                         break;
517                 case 'P':
518                         /* filename */
519                         s = chomp(p);
520                         /* DOC: section name */
521                         while (isspace(*s))
522                                 s++;
523                         docsection(p, s);
524                         break;
525                 case 'C':
526                         chomp(p);
527                         if (findall)
528                                 findall(p);
529                         break;
530                 default:
531                         defaultline(line);
532                 }
533         }
534         fflush(stdout);
535 }
536 
537 /*
538  * Is this a RestructuredText template?  Answer the question by seeing if its
539  * name ends in ".rst".
540  */
541 static int is_rst(const char *file)
542 {
543         char *dot = strrchr(file, '.');
544 
545         return dot && !strcmp(dot + 1, "rst");
546 }
547 
548 enum opts {
549         OPT_DOCBOOK,
550         OPT_RST,
551         OPT_HELP,
552 };
553 
554 int main(int argc, char *argv[])
555 {
556         const char *subcommand, *filename;
557         FILE * infile;
558         int i;
559 
560         srctree = getenv("SRCTREE");
561         if (!srctree)
562                 srctree = getcwd(NULL, 0);
563         kernsrctree = getenv("KBUILD_SRC");
564         if (!kernsrctree || !*kernsrctree)
565                 kernsrctree = srctree;
566 
567         for (;;) {
568                 int c;
569                 struct option opts[] = {
570                         { "docbook",    no_argument, NULL, OPT_DOCBOOK },
571                         { "rst",        no_argument, NULL, OPT_RST },
572                         { "help",       no_argument, NULL, OPT_HELP },
573                         {}
574                 };
575 
576                 c = getopt_long_only(argc, argv, "", opts, NULL);
577                 if (c == -1)
578                         break;
579 
580                 switch (c) {
581                 case OPT_DOCBOOK:
582                         file_format = FORMAT_DOCBOOK;
583                         break;
584                 case OPT_RST:
585                         file_format = FORMAT_RST;
586                         break;
587                 case OPT_HELP:
588                         usage();
589                         return 0;
590                 default:
591                 case '?':
592                         usage();
593                         return 1;
594                 }
595         }
596 
597         argc -= optind;
598         argv += optind;
599 
600         if (argc != 2) {
601                 usage();
602                 exit(1);
603         }
604 
605         subcommand = argv[0];
606         filename = argv[1];
607 
608         if (file_format == FORMAT_AUTO)
609                 file_format = is_rst(filename) ? FORMAT_RST : FORMAT_DOCBOOK;
610 
611         /* Open file, exit on error */
612         infile = fopen(filename, "r");
613         if (infile == NULL) {
614                 fprintf(stderr, "docproc: ");
615                 perror(filename);
616                 exit(2);
617         }
618 
619         if (strcmp("doc", subcommand) == 0) {
620                 if (file_format == FORMAT_RST) {
621                         time_t t = time(NULL);
622                         printf(".. generated from %s by docproc %s\n",
623                                filename, ctime(&t));
624                 }
625 
626                 /* Need to do this in two passes.
627                  * First pass is used to collect all symbols exported
628                  * in the various files;
629                  * Second pass generate the documentation.
630                  * This is required because some functions are declared
631                  * and exported in different files :-((
632                  */
633                 /* Collect symbols */
634                 defaultline       = noaction;
635                 internalfunctions = find_export_symbols;
636                 externalfunctions = find_export_symbols;
637                 symbolsonly       = find_export_symbols;
638                 singlefunctions   = noaction2;
639                 docsection        = noaction2;
640                 findall           = find_all_symbols;
641                 parse_file(infile);
642 
643                 /* Rewind to start from beginning of file again */
644                 fseek(infile, 0, SEEK_SET);
645                 defaultline       = printline;
646                 internalfunctions = intfunc;
647                 externalfunctions = extfunc;
648                 symbolsonly       = printline;
649                 singlefunctions   = singfunc;
650                 docsection        = docsect;
651                 findall           = NULL;
652 
653                 parse_file(infile);
654 
655                 for (i = 0; i < all_list_len; i++) {
656                         if (!all_list[i])
657                                 continue;
658                         fprintf(stderr, "Warning: didn't use docs for %s\n",
659                                 all_list[i]);
660                 }
661         } else if (strcmp("depend", subcommand) == 0) {
662                 /* Create first part of dependency chain
663                  * file.tmpl */
664                 printf("%s\t", filename);
665                 defaultline       = noaction;
666                 internalfunctions = adddep;
667                 externalfunctions = adddep;
668                 symbolsonly       = adddep;
669                 singlefunctions   = adddep2;
670                 docsection        = adddep2;
671                 findall           = adddep;
672                 parse_file(infile);
673                 printf("\n");
674         } else {
675                 fprintf(stderr, "Unknown option: %s\n", subcommand);
676                 exit(1);
677         }
678         fclose(infile);
679         fflush(stdout);
680         return exitstatus;
681 }
682 

This page was automatically generated by LXR 0.3.1 (source).  •  Linux is a registered trademark of Linus Torvalds  •  Contact us