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
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
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:
40 #include <sys/types.h>
44 /* exitstatus is used to keep track of any failing calls to kernel-doc,
45 * but execution continues. */
48 typedef void DFL(char *);
51 typedef void FILEONLY(char * file);
52 FILEONLY *internalfunctions;
53 FILEONLY *externalfunctions;
54 FILEONLY *symbolsonly;
56 typedef void FILELINE(char * file, char * line);
57 FILELINE * singlefunctions;
58 FILELINE * entity_system;
60 #define MAXLINESZ 2048
62 #define KERNELDOCPATH "scripts/"
63 #define KERNELDOC "kernel-doc"
64 #define DOCBOOK "-docbook"
65 #define FUNCTION "-function"
66 #define NOFUNCTION "-nofunction"
70 fprintf(stderr, "Usage: docproc {doc|depend} file\n");
71 fprintf(stderr, "Input is read from file.tmpl. Output is sent to stdout\n");
72 fprintf(stderr, "doc: frontend when generating kernel documentation\n");
73 fprintf(stderr, "depend: generate list of files referenced within file\n");
77 * Execute kernel-doc with parameters givin in svec
79 void exec_kernel_doc(char **svec)
86 /* Make sure output generated so far are flushed */
93 rflen = strlen(getenv("SRCTREE"));
94 rflen += strlen(KERNELDOCPATH KERNELDOC);
95 real_filename = alloca(rflen + 1);
96 strcpy(real_filename, getenv("SRCTREE"));
97 strcat(real_filename, KERNELDOCPATH KERNELDOC);
98 execvp(real_filename, svec);
99 fprintf(stderr, "exec ");
100 perror(real_filename);
103 waitpid(pid, &ret ,0);
106 exitstatus |= WEXITSTATUS(ret);
111 /* Types used to create list of all exported symbols in a number of files */
120 struct symbols *symbollist;
124 struct symfile symfilelist[MAXFILES];
127 void add_new_symbol(struct symfile *sym, char * symname)
130 realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *));
131 sym->symbollist[sym->symbolcnt++].name = strdup(symname);
134 /* Add a filename to the list */
135 struct symfile * add_new_file(char * filename)
137 symfilelist[symfilecnt++].filename = strdup(filename);
138 return &symfilelist[symfilecnt - 1];
140 /* Check if file already are present in the list */
141 struct symfile * filename_exist(char * filename)
144 for (i=0; i < symfilecnt; i++)
145 if (strcmp(symfilelist[i].filename, filename) == 0)
146 return &symfilelist[i];
151 * List all files referenced within the template file.
152 * Files are separated by tabs.
154 void adddep(char * file) { printf("\t%s", file); }
155 void adddep2(char * file, char * line) { line = line; adddep(file); }
156 void noaction(char * line) { line = line; }
157 void noaction2(char * file, char * line) { file = file; line = line; }
159 /* Echo the line without further action */
160 void printline(char * line) { printf("%s", line); }
163 * Find all symbols exported with EXPORT_SYMBOL and EXPORT_SYMBOL_GPL
165 * All symbols located are stored in symfilelist.
167 void find_export_symbols(char * filename)
171 char line[MAXLINESZ];
172 if (filename_exist(filename) == NULL) {
173 int rflen = strlen(getenv("SRCTREE")) + strlen(filename);
174 char *real_filename = alloca(rflen + 1);
175 strcpy(real_filename, getenv("SRCTREE"));
176 strcat(real_filename, filename);
177 sym = add_new_file(filename);
178 fp = fopen(real_filename, "r");
181 fprintf(stderr, "docproc: ");
182 perror(real_filename);
184 while (fgets(line, MAXLINESZ, fp)) {
187 if (((p = strstr(line, "EXPORT_SYMBOL_GPL")) != 0) ||
188 ((p = strstr(line, "EXPORT_SYMBOL")) != 0)) {
189 /* Skip EXPORT_SYMBOL{_GPL} */
190 while (isalnum(*p) || *p == '_')
192 /* Remove paranteses and additional ws */
196 continue; /* Syntax error? */
202 while (isalnum(*e) || *e == '_')
205 add_new_symbol(sym, p);
213 * Document all external or internal functions in a file.
214 * Call kernel-doc with following parameters:
215 * kernel-doc -docbook -nofunction function_name1 filename
216 * function names are obtained from all the src files
217 * by find_export_symbols.
218 * intfunc uses -nofunction
219 * extfunc uses -function
221 void docfunctions(char * filename, char * type)
228 for (i=0; i <= symfilecnt; i++)
229 symcnt += symfilelist[i].symbolcnt;
230 vec = malloc((2 + 2 * symcnt + 2) * sizeof(char*));
235 vec[idx++] = KERNELDOC;
236 vec[idx++] = DOCBOOK;
237 for (i=0; i < symfilecnt; i++) {
238 struct symfile * sym = &symfilelist[i];
239 for (j=0; j < sym->symbolcnt; j++) {
241 vec[idx++] = sym->symbollist[j].name;
244 vec[idx++] = filename;
246 printf("<!-- %s -->\n", filename);
247 exec_kernel_doc(vec);
251 void intfunc(char * filename) { docfunctions(filename, NOFUNCTION); }
252 void extfunc(char * filename) { docfunctions(filename, FUNCTION); }
255 * Document specific function(s) in a file.
256 * Call kernel-doc with the following parameters:
257 * kernel-doc -docbook -function function1 [-function function2]
259 void singfunc(char * filename, char * line)
261 char *vec[200]; /* Enough for specific functions */
264 vec[idx++] = KERNELDOC;
265 vec[idx++] = DOCBOOK;
267 /* Split line up in individual parameters preceeded by FUNCTION */
268 for (i=0; line[i]; i++) {
269 if (isspace(line[i])) {
276 vec[idx++] = FUNCTION;
277 vec[idx++] = &line[i];
280 vec[idx++] = filename;
282 exec_kernel_doc(vec);
286 * Parse file, calling action specific functions for:
287 * 1) Lines containing !E
288 * 2) Lines containing !I
289 * 3) Lines containing !D
290 * 4) Lines containing !F
291 * 5) Default lines - lines not matching the above
293 void parse_file(FILE *infile)
295 char line[MAXLINESZ];
297 while (fgets(line, MAXLINESZ, infile)) {
298 if (line[0] == '!') {
302 while (*s && !isspace(*s)) s++;
304 externalfunctions(line+2);
307 while (*s && !isspace(*s)) s++;
309 internalfunctions(line+2);
312 while (*s && !isspace(*s)) s++;
318 while (*s && !isspace(*s)) s++;
323 singlefunctions(line +2, s);
337 int main(int argc, char **argv)
344 /* Open file, exit on error */
345 infile = fopen(argv[2], "r");
346 if (infile == NULL) {
347 fprintf(stderr, "docproc: ");
352 if (strcmp("doc", argv[1]) == 0)
354 /* Need to do this in two passes.
355 * First pass is used to collect all symbols exported
356 * in the various files.
357 * Second pass generate the documentation.
358 * This is required because function are declared
359 * and exported in different files :-((
361 /* Collect symbols */
362 defaultline = noaction;
363 internalfunctions = find_export_symbols;
364 externalfunctions = find_export_symbols;
365 symbolsonly = find_export_symbols;
366 singlefunctions = noaction2;
369 /* Rewind to start from beginning of file again */
370 fseek(infile, 0, SEEK_SET);
371 defaultline = printline;
372 internalfunctions = intfunc;
373 externalfunctions = extfunc;
374 symbolsonly = printline;
375 singlefunctions = singfunc;
379 else if (strcmp("depend", argv[1]) == 0)
381 /* Create first part of dependency chain
383 printf("%s\t", argv[2]);
384 defaultline = noaction;
385 internalfunctions = adddep;
386 externalfunctions = adddep;
387 symbolsonly = adddep;
388 singlefunctions = adddep2;
394 fprintf(stderr, "Unknown option: %s\n", argv[1]);