docproc.c 14 KB

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