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>
43 /* exitstatus is used to keep track of any failing calls to kernel-doc,
44 * but execution continues. */
47 typedef void DFL(char *);
50 typedef void FILEONLY(char * file
);
51 FILEONLY
*internalfunctions
;
52 FILEONLY
*externalfunctions
;
53 FILEONLY
*symbolsonly
;
55 typedef void FILELINE(char * file
, char * line
);
56 FILELINE
* singlefunctions
;
57 FILELINE
* entity_system
;
59 #define MAXLINESZ 2048
61 #define KERNELDOCPATH "scripts/"
62 #define KERNELDOC "kernel-doc"
63 #define DOCBOOK "-docbook"
64 #define FUNCTION "-function"
65 #define NOFUNCTION "-nofunction"
69 fprintf(stderr
, "Usage: docproc {doc|depend} file\n");
70 fprintf(stderr
, "Input is read from file.tmpl. Output is sent to stdout\n");
71 fprintf(stderr
, "doc: frontend when generating kernel documentation\n");
72 fprintf(stderr
, "depend: generate list of files referenced within file\n");
76 * Execute kernel-doc with parameters givin in svec
78 void exec_kernel_doc(char **svec
)
82 /* Make sure output generated so far are flushed */
89 execvp(KERNELDOCPATH KERNELDOC
, svec
);
90 perror("exec " KERNELDOCPATH KERNELDOC
);
93 waitpid(pid
, &ret
,0);
96 exitstatus
|= WEXITSTATUS(ret
);
101 /* Types used to create list of all exported symbols in a number of files */
110 struct symbols
*symbollist
;
114 struct symfile symfilelist
[MAXFILES
];
117 void add_new_symbol(struct symfile
*sym
, char * symname
)
120 realloc(sym
->symbollist
, (sym
->symbolcnt
+ 1) * sizeof(char *));
121 sym
->symbollist
[sym
->symbolcnt
++].name
= strdup(symname
);
124 /* Add a filename to the list */
125 struct symfile
* add_new_file(char * filename
)
127 symfilelist
[symfilecnt
++].filename
= strdup(filename
);
128 return &symfilelist
[symfilecnt
- 1];
130 /* Check if file already are present in the list */
131 struct symfile
* filename_exist(char * filename
)
134 for (i
=0; i
< symfilecnt
; i
++)
135 if (strcmp(symfilelist
[i
].filename
, filename
) == 0)
136 return &symfilelist
[i
];
141 * List all files referenced within the template file.
142 * Files are separated by tabs.
144 void adddep(char * file
) { printf("\t%s", file
); }
145 void adddep2(char * file
, char * line
) { line
= line
; adddep(file
); }
146 void noaction(char * line
) { line
= line
; }
147 void noaction2(char * file
, char * line
) { file
= file
; line
= line
; }
149 /* Echo the line without further action */
150 void printline(char * line
) { printf("%s", line
); }
153 * Find all symbols exported with EXPORT_SYMBOL and EXPORT_SYMBOL_GPL
155 * All symbols located are stored in symfilelist.
157 void find_export_symbols(char * filename
)
161 char line
[MAXLINESZ
];
162 if (filename_exist(filename
) == NULL
) {
163 sym
= add_new_file(filename
);
164 fp
= fopen(filename
, "r");
167 fprintf(stderr
, "docproc: ");
170 while(fgets(line
, MAXLINESZ
, fp
)) {
173 if (((p
= strstr(line
, "EXPORT_SYMBOL_GPL")) != 0) ||
174 ((p
= strstr(line
, "EXPORT_SYMBOL")) != 0)) {
175 /* Skip EXPORT_SYMBOL{_GPL} */
176 while (isalnum(*p
) || *p
== '_')
178 /* Remove paranteses and additional ws */
182 continue; /* Syntax error? */
188 while (isalnum(*e
) || *e
== '_')
191 add_new_symbol(sym
, p
);
199 * Document all external or internal functions in a file.
200 * Call kernel-doc with following parameters:
201 * kernel-doc -docbook -nofunction function_name1 filename
202 * function names are obtained from all the the src files
203 * by find_export_symbols.
204 * intfunc uses -nofunction
205 * extfunc uses -function
207 void docfunctions(char * filename
, char * type
)
214 for (i
=0; i
<= symfilecnt
; i
++)
215 symcnt
+= symfilelist
[i
].symbolcnt
;
216 vec
= malloc((2 + 2 * symcnt
+ 2) * sizeof(char*));
221 vec
[idx
++] = KERNELDOC
;
222 vec
[idx
++] = DOCBOOK
;
223 for (i
=0; i
< symfilecnt
; i
++) {
224 struct symfile
* sym
= &symfilelist
[i
];
225 for (j
=0; j
< sym
->symbolcnt
; j
++) {
227 vec
[idx
++] = sym
->symbollist
[j
].name
;
230 vec
[idx
++] = filename
;
232 printf("<!-- %s -->\n", filename
);
233 exec_kernel_doc(vec
);
237 void intfunc(char * filename
) { docfunctions(filename
, NOFUNCTION
); }
238 void extfunc(char * filename
) { docfunctions(filename
, FUNCTION
); }
241 * Document spÄecific function(s) in a file.
242 * Call kernel-doc with the following parameters:
243 * kernel-doc -docbook -function function1 [-function function2]
245 void singfunc(char * filename
, char * line
)
247 char *vec
[200]; /* Enough for specific functions */
250 vec
[idx
++] = KERNELDOC
;
251 vec
[idx
++] = DOCBOOK
;
253 /* Split line up in individual parameters preceeded by FUNCTION */
254 for (i
=0; line
[i
]; i
++) {
255 if (isspace(line
[i
])) {
262 vec
[idx
++] = FUNCTION
;
263 vec
[idx
++] = &line
[i
];
266 vec
[idx
++] = filename
;
268 exec_kernel_doc(vec
);
272 * Parse file, calling action specific functions for:
273 * 1) Lines containing !E
274 * 2) Lines containing !I
275 * 3) Lines containing !D
276 * 4) Lines containing !F
277 * 5) Default lines - lines not matching the above
279 void parse_file(FILE *infile
)
281 char line
[MAXLINESZ
];
283 while(fgets(line
, MAXLINESZ
, infile
)) {
284 if (line
[0] == '!') {
288 while (*s
&& !isspace(*s
)) s
++;
290 externalfunctions(line
+2);
293 while (*s
&& !isspace(*s
)) s
++;
295 internalfunctions(line
+2);
298 while (*s
&& !isspace(*s
)) s
++;
304 while (*s
&& !isspace(*s
)) s
++;
309 singlefunctions(line
+2, s
);
323 int main(int argc
, char *argv
[])
330 /* Open file, exit on error */
331 infile
= fopen(argv
[2], "r");
332 if (infile
== NULL
) {
333 fprintf(stderr
, "docproc: ");
338 if (strcmp("doc", argv
[1]) == 0)
340 /* Need to do this in two passes.
341 * First pass is used to collect all symbols exported
342 * in the various files.
343 * Second pass generate the documentation.
344 * This is required because function are declared
345 * and exported in different files :-((
347 /* Collect symbols */
348 defaultline
= noaction
;
349 internalfunctions
= find_export_symbols
;
350 externalfunctions
= find_export_symbols
;
351 symbolsonly
= find_export_symbols
;
352 singlefunctions
= noaction2
;
355 /* Rewind to start from beginning of file again */
356 fseek(infile
, 0, SEEK_SET
);
357 defaultline
= printline
;
358 internalfunctions
= intfunc
;
359 externalfunctions
= extfunc
;
360 symbolsonly
= printline
;
361 singlefunctions
= singfunc
;
365 else if (strcmp("depend", argv
[1]) == 0)
367 /* Create first part of dependency chain
369 printf("%s\t", argv
[2]);
370 defaultline
= noaction
;
371 internalfunctions
= adddep
;
372 externalfunctions
= adddep
;
373 symbolsonly
= adddep
;
374 singlefunctions
= adddep2
;
380 fprintf(stderr
, "Unknown option: %s\n", argv
[1]);