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