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