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