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 }