3
0

docproc.c 9.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400
  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 are scanned for
  14. * any exported sympols "EXPORT_SYMBOL()" statements.
  15. * This is used to create proper -function and
  16. * -nofunction arguments in calls to kernel-doc.
  17. * Usage: docproc doc file.tmpl
  18. *
  19. * dependency-generator:
  20. * Scans the template file and list all files
  21. * referenced in a format recognized by make.
  22. * Usage: docproc depend file.tmpl
  23. * Writes dependency information to stdout
  24. * in the following format:
  25. * file.tmpl src.c src2.c
  26. * The filenames are obtained from the following constructs:
  27. * !Efilename
  28. * !Ifilename
  29. * !Dfilename
  30. * !Ffilename
  31. *
  32. */
  33. #include <stdio.h>
  34. #include <stdlib.h>
  35. #include <string.h>
  36. #include <ctype.h>
  37. #include <unistd.h>
  38. #include <limits.h>
  39. #include <sys/types.h>
  40. #include <sys/wait.h>
  41. //bbox disabled: #include <alloca.h>
  42. /* exitstatus is used to keep track of any failing calls to kernel-doc,
  43. * but execution continues. */
  44. int exitstatus = 0;
  45. typedef void DFL(char *);
  46. DFL *defaultline;
  47. typedef void FILEONLY(char * file);
  48. FILEONLY *internalfunctions;
  49. FILEONLY *externalfunctions;
  50. FILEONLY *symbolsonly;
  51. typedef void FILELINE(char * file, char * line);
  52. FILELINE * singlefunctions;
  53. FILELINE * entity_system;
  54. #define MAXLINESZ 2048
  55. #define MAXFILES 250
  56. #define KERNELDOCPATH "scripts/"
  57. #define KERNELDOC "kernel-doc"
  58. #define DOCBOOK "-docbook"
  59. #define FUNCTION "-function"
  60. #define NOFUNCTION "-nofunction"
  61. void usage (void)
  62. {
  63. fprintf(stderr, "Usage: docproc {doc|depend} file\n");
  64. fprintf(stderr, "Input is read from file.tmpl. Output is sent to stdout\n");
  65. fprintf(stderr, "doc: frontend when generating kernel documentation\n");
  66. fprintf(stderr, "depend: generate list of files referenced within file\n");
  67. }
  68. /*
  69. * Execute kernel-doc with parameters givin in svec
  70. */
  71. void exec_kernel_doc(char **svec)
  72. {
  73. pid_t pid;
  74. int ret;
  75. char *real_filename;
  76. int rflen;
  77. /* Make sure output generated so far are flushed */
  78. fflush(stdout);
  79. switch(pid=fork()) {
  80. case -1:
  81. perror("vfork"+1);
  82. exit(1);
  83. case 0:
  84. rflen = strlen(getenv("SRCTREE"));
  85. rflen += strlen(KERNELDOCPATH KERNELDOC);
  86. real_filename = alloca(rflen + 1);
  87. strcpy(real_filename, getenv("SRCTREE"));
  88. strcat(real_filename, KERNELDOCPATH KERNELDOC);
  89. execvp(real_filename, svec);
  90. fprintf(stderr, "exec ");
  91. perror(real_filename);
  92. exit(1);
  93. default:
  94. waitpid(pid, &ret ,0);
  95. }
  96. if (WIFEXITED(ret))
  97. exitstatus |= WEXITSTATUS(ret);
  98. else
  99. exitstatus = 0xff;
  100. }
  101. /* Types used to create list of all exported symbols in a number of files */
  102. struct symbols
  103. {
  104. char *name;
  105. };
  106. struct symfile
  107. {
  108. char *filename;
  109. struct symbols *symbollist;
  110. int symbolcnt;
  111. };
  112. struct symfile symfilelist[MAXFILES];
  113. int symfilecnt = 0;
  114. void add_new_symbol(struct symfile *sym, char * symname)
  115. {
  116. sym->symbollist =
  117. realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *));
  118. sym->symbollist[sym->symbolcnt++].name = strdup(symname);
  119. }
  120. /* Add a filename to the list */
  121. struct symfile * add_new_file(char * filename)
  122. {
  123. symfilelist[symfilecnt++].filename = strdup(filename);
  124. return &symfilelist[symfilecnt - 1];
  125. }
  126. /* Check if file already are present in the list */
  127. struct symfile * filename_exist(char * filename)
  128. {
  129. int i;
  130. for (i=0; i < symfilecnt; i++)
  131. if (strcmp(symfilelist[i].filename, filename) == 0)
  132. return &symfilelist[i];
  133. return NULL;
  134. }
  135. /*
  136. * List all files referenced within the template file.
  137. * Files are separated by tabs.
  138. */
  139. void adddep(char * file) { printf("\t%s", file); }
  140. void adddep2(char * file, char * line) { line = line; adddep(file); }
  141. void noaction(char * line) { line = line; }
  142. void noaction2(char * file, char * line) { file = file; line = line; }
  143. /* Echo the line without further action */
  144. void printline(char * line) { printf("%s", line); }
  145. /*
  146. * Find all symbols exported with EXPORT_SYMBOL and EXPORT_SYMBOL_GPL
  147. * in filename.
  148. * All symbols located are stored in symfilelist.
  149. */
  150. void find_export_symbols(char * filename)
  151. {
  152. FILE * fp;
  153. struct symfile *sym;
  154. char line[MAXLINESZ];
  155. if (filename_exist(filename) == NULL) {
  156. int rflen = strlen(getenv("SRCTREE")) + strlen(filename);
  157. char *real_filename = alloca(rflen + 1);
  158. strcpy(real_filename, getenv("SRCTREE"));
  159. strcat(real_filename, filename);
  160. sym = add_new_file(filename);
  161. fp = fopen(real_filename, "r");
  162. if (fp == NULL)
  163. {
  164. fprintf(stderr, "docproc: ");
  165. perror(real_filename);
  166. }
  167. while (fgets(line, MAXLINESZ, fp)) {
  168. char *p;
  169. char *e;
  170. if (((p = strstr(line, "EXPORT_SYMBOL_GPL")) != 0) ||
  171. ((p = strstr(line, "EXPORT_SYMBOL")) != 0)) {
  172. /* Skip EXPORT_SYMBOL{_GPL} */
  173. while (isalnum(*p) || *p == '_')
  174. p++;
  175. /* Remove paranteses and additional ws */
  176. while (isspace(*p))
  177. p++;
  178. if (*p != '(')
  179. continue; /* Syntax error? */
  180. else
  181. p++;
  182. while (isspace(*p))
  183. p++;
  184. e = p;
  185. while (isalnum(*e) || *e == '_')
  186. e++;
  187. *e = '\0';
  188. add_new_symbol(sym, p);
  189. }
  190. }
  191. fclose(fp);
  192. }
  193. }
  194. /*
  195. * Document all external or internal functions in a file.
  196. * Call kernel-doc with following parameters:
  197. * kernel-doc -docbook -nofunction function_name1 filename
  198. * function names are obtained from all the src files
  199. * by find_export_symbols.
  200. * intfunc uses -nofunction
  201. * extfunc uses -function
  202. */
  203. void docfunctions(char * filename, char * type)
  204. {
  205. int i,j;
  206. int symcnt = 0;
  207. int idx = 0;
  208. char **vec;
  209. for (i=0; i <= symfilecnt; i++)
  210. symcnt += symfilelist[i].symbolcnt;
  211. vec = malloc((2 + 2 * symcnt + 2) * sizeof(char*));
  212. if (vec == NULL) {
  213. perror("docproc: ");
  214. exit(1);
  215. }
  216. vec[idx++] = KERNELDOC;
  217. vec[idx++] = DOCBOOK;
  218. for (i=0; i < symfilecnt; i++) {
  219. struct symfile * sym = &symfilelist[i];
  220. for (j=0; j < sym->symbolcnt; j++) {
  221. vec[idx++] = type;
  222. vec[idx++] = sym->symbollist[j].name;
  223. }
  224. }
  225. vec[idx++] = filename;
  226. vec[idx] = NULL;
  227. printf("<!-- %s -->\n", filename);
  228. exec_kernel_doc(vec);
  229. fflush(stdout);
  230. free(vec);
  231. }
  232. void intfunc(char * filename) { docfunctions(filename, NOFUNCTION); }
  233. void extfunc(char * filename) { docfunctions(filename, FUNCTION); }
  234. /*
  235. * Document specific function(s) in a file.
  236. * Call kernel-doc with the following parameters:
  237. * kernel-doc -docbook -function function1 [-function function2]
  238. */
  239. void singfunc(char * filename, char * line)
  240. {
  241. char *vec[200]; /* Enough for specific functions */
  242. int i, idx = 0;
  243. int startofsym = 1;
  244. vec[idx++] = KERNELDOC;
  245. vec[idx++] = DOCBOOK;
  246. /* Split line up in individual parameters preceded by FUNCTION */
  247. for (i=0; line[i]; i++) {
  248. if (isspace(line[i])) {
  249. line[i] = '\0';
  250. startofsym = 1;
  251. continue;
  252. }
  253. if (startofsym) {
  254. startofsym = 0;
  255. vec[idx++] = FUNCTION;
  256. vec[idx++] = &line[i];
  257. }
  258. }
  259. vec[idx++] = filename;
  260. vec[idx] = NULL;
  261. exec_kernel_doc(vec);
  262. }
  263. /*
  264. * Parse file, calling action specific functions for:
  265. * 1) Lines containing !E
  266. * 2) Lines containing !I
  267. * 3) Lines containing !D
  268. * 4) Lines containing !F
  269. * 5) Default lines - lines not matching the above
  270. */
  271. void parse_file(FILE *infile)
  272. {
  273. char line[MAXLINESZ];
  274. char * s;
  275. while (fgets(line, MAXLINESZ, infile)) {
  276. if (line[0] == '!') {
  277. s = line + 2;
  278. switch (line[1]) {
  279. case 'E':
  280. while (*s && !isspace(*s)) s++;
  281. *s = '\0';
  282. externalfunctions(line+2);
  283. break;
  284. case 'I':
  285. while (*s && !isspace(*s)) s++;
  286. *s = '\0';
  287. internalfunctions(line+2);
  288. break;
  289. case 'D':
  290. while (*s && !isspace(*s)) s++;
  291. *s = '\0';
  292. symbolsonly(line+2);
  293. break;
  294. case 'F':
  295. /* filename */
  296. while (*s && !isspace(*s)) s++;
  297. *s++ = '\0';
  298. /* function names */
  299. while (isspace(*s))
  300. s++;
  301. singlefunctions(line +2, s);
  302. break;
  303. default:
  304. defaultline(line);
  305. }
  306. }
  307. else {
  308. defaultline(line);
  309. }
  310. }
  311. fflush(stdout);
  312. }
  313. int main(int argc, char **argv)
  314. {
  315. FILE * infile;
  316. if (argc != 3) {
  317. usage();
  318. exit(1);
  319. }
  320. /* Open file, exit on error */
  321. infile = fopen(argv[2], "r");
  322. if (infile == NULL) {
  323. fprintf(stderr, "docproc: ");
  324. perror(argv[2]);
  325. exit(2);
  326. }
  327. if (strcmp("doc", argv[1]) == 0)
  328. {
  329. /* Need to do this in two passes.
  330. * First pass is used to collect all symbols exported
  331. * in the various files.
  332. * Second pass generate the documentation.
  333. * This is required because function are declared
  334. * and exported in different files :-((
  335. */
  336. /* Collect symbols */
  337. defaultline = noaction;
  338. internalfunctions = find_export_symbols;
  339. externalfunctions = find_export_symbols;
  340. symbolsonly = find_export_symbols;
  341. singlefunctions = noaction2;
  342. parse_file(infile);
  343. /* Rewind to start from beginning of file again */
  344. fseek(infile, 0, SEEK_SET);
  345. defaultline = printline;
  346. internalfunctions = intfunc;
  347. externalfunctions = extfunc;
  348. symbolsonly = printline;
  349. singlefunctions = singfunc;
  350. parse_file(infile);
  351. }
  352. else if (strcmp("depend", argv[1]) == 0)
  353. {
  354. /* Create first part of dependency chain
  355. * file.tmpl */
  356. printf("%s\t", argv[2]);
  357. defaultline = noaction;
  358. internalfunctions = adddep;
  359. externalfunctions = adddep;
  360. symbolsonly = adddep;
  361. singlefunctions = adddep2;
  362. parse_file(infile);
  363. printf("\n");
  364. }
  365. else
  366. {
  367. fprintf(stderr, "Unknown option: %s\n", argv[1]);
  368. exit(1);
  369. }
  370. fclose(infile);
  371. fflush(stdout);
  372. return exitstatus;
  373. }