kerneldoc: Implant DocBook from Linux kernel

Pull slightly modified version of Documentation/DocBook, the related perl
script scripts/kernel-doc and the scripts/docproc.c from Linux kernel and
implant it into U-Boot. This will allow smooth generation of kerneldoc
style documentation.

It was necessary to modify the DocBook/Makefile to work with U-Boot build
system. The changes were only minor though and involved replacing the kbuild
specific parts.

It was also necessary to replace use of variables like KERNEL_VERSION with
U_BOOT_VERSION, strings like Linux kernel with U-Boot Bootloader etc. so
the generated result actually matches.

Finally, it was necessary to adjust docproc.c, since the documentation in
U-Boot is located in doc/DocBook instead of Documentation/DocBook as is in
case of the Linux kernel.

Some parts of the DocBook Makefile are unused, but to allow easier sync with
Linux kernel, these parts are still left in. The targets enabled now are
"htmldocs" "pdfdocs" "psdocs" "xmldocs" and "cleandocs" to remove the results
of documentation build.

Linux scripts/docproc.c:
commit f0f3ca8d967462dafb815412b14ca3339b9817a6
Date:   Wed Jun 15 11:53:13 2011 +0200

Linux scripts/kernel-doc:
commit 1b40c1944db445c1de1c47ffd8cd426167f488e8
Date:   Sun Aug 12 10:46:15 2012 +0200

Linux Documentation/DocBook:
commit bb8187d35f820671d6dd76700d77a6b55f95e2c5
Date:   Thu May 17 19:06:13 2012 -0400

Signed-off-by: Marek Vasut <marex@denx.de>
This commit is contained in:
Marek Vasut 2012-10-06 14:04:58 +00:00 committed by Tom Rini
parent c50204a517
commit 30ff89189b
9 changed files with 3430 additions and 2 deletions

View file

@ -715,6 +715,9 @@ easylogo env gdb:
$(MAKE) -C tools/$@ all MTD_VERSION=${MTD_VERSION}
gdbtools: gdb
xmldocs pdfdocs psdocs htmldocs mandocs: tools/kernel-doc/docproc
$(MAKE) U_BOOT_VERSION=$(U_BOOT_VERSION) -C doc/DocBook/ $@
tools-all: easylogo env gdb $(VERSION_FILE) $(TIMESTAMP_FILE)
$(MAKE) -C tools HOST_TOOLS_ALL=y
@ -799,7 +802,8 @@ clean:
$(obj)tools/mk{env,}image $(obj)tools/mpc86x_clk \
$(obj)tools/mk{smdk5250,}spl \
$(obj)tools/mxsboot \
$(obj)tools/ncb $(obj)tools/ubsha1
$(obj)tools/ncb $(obj)tools/ubsha1 \
$(obj)tools/kernel-doc/docproc
@rm -f $(obj)board/cray/L1/{bootscript.c,bootscript.image} \
$(obj)board/matrix_vision/*/bootscript.img \
$(obj)board/voiceblue/eeprom \
@ -812,6 +816,7 @@ clean:
@rm -f $(obj)include/generated/asm-offsets.h
@rm -f $(obj)$(CPUDIR)/$(SOC)/asm-offsets.s
@rm -f $(TIMESTAMP_FILE) $(VERSION_FILE)
@$(MAKE) -C doc/DocBook/ cleandocs
@find $(OBJTREE) -type f \
\( -name 'core' -o -name '*.bak' -o -name '*~' -o -name '*.su' \
-o -name '*.o' -o -name '*.a' -o -name '*.exe' \) -print \

15
doc/DocBook/.gitignore vendored Normal file
View file

@ -0,0 +1,15 @@
*/
*.xml
*.ps
*.pdf
*.html
*.9.gz
*.9
*.aux
*.dvi
*.log
*.out
*.png
*.gif
media-indices.tmpl
media-entities.tmpl

229
doc/DocBook/Makefile Normal file
View file

@ -0,0 +1,229 @@
###
# This makefile is used to generate the kernel documentation,
# primarily based on in-line comments in various source files.
# See doc/kernel-doc-nano-HOWTO.txt for instruction in how
# to document the SRC - and how to read it.
# To add a new book the only step required is to add the book to the
# list of DOCBOOKS.
include $(TOPDIR)/config.mk
DOCBOOKS :=
###
# The build process is as follows (targets):
# (xmldocs) [by docproc]
# file.tmpl --> file.xml +--> file.ps (psdocs) [by db2ps or xmlto]
# +--> file.pdf (pdfdocs) [by db2pdf or xmlto]
# +--> DIR=file (htmldocs) [by xmlto]
# +--> man/ (mandocs) [by xmlto]
# for PDF and PS output you can choose between xmlto and docbook-utils tools
PDF_METHOD = $(prefer-db2x)
PS_METHOD = $(prefer-db2x)
###
# The targets that may be used.
PHONY += $(obj).depend xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs
BOOKS := $(addprefix $(OBJTREE)/doc/DocBook/,$(DOCBOOKS))
xmldocs: $(BOOKS)
sgmldocs: xmldocs
PS := $(patsubst %.xml, %.ps, $(BOOKS))
psdocs: $(PS)
PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
pdfdocs: $(PDF)
HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
htmldocs: $(HTML)
$(call build_main_index)
$(call build_images)
$(call install_media_images)
MAN := $(patsubst %.xml, %.9, $(BOOKS))
mandocs: $(MAN)
installmandocs: mandocs
mkdir -p /usr/local/man/man9/
install doc/DocBook/man/*.9.gz /usr/local/man/man9/
###
#External programs used
KERNELDOC = $(SRCTREE)/tools/kernel-doc/kernel-doc
DOCPROC = $(OBJTREE)/tools/kernel-doc/docproc
XMLTOFLAGS = -m $(SRCTREE)/doc/DocBook/stylesheet.xsl
XMLTOFLAGS += --skip-validation
###
# DOCPROC is used for two purposes:
# 1) To generate a dependency list for a .tmpl file
# 2) To preprocess a .tmpl file and call kernel-doc with
# appropriate parameters.
# The following rules are used to generate the .xml documentation
# required to generate the final targets. (ps, pdf, html).
%.xml: %.tmpl
$(DOCPROC) doc $< >$@
ifeq ($@, "cleandocs")
sinclude $(obj).depend
$(obj).depend: $(patsubst %.xml, %.tmpl, $(DOCBOOKS))
rm -f $(obj).depend ; \
touch $(obj).depend ; \
for file in $^ ; do \
xmlfile=`echo "$${file}" | \
sed "s/tmpl$$/xml/"` ; \
echo -n "$${xmlfile}: ">> $(obj).depend ; \
$(DOCPROC) depend $$file >> $(obj).depend ; \
echo -e "\n\t$(DOCPROC) doc $< >$${xmlfile} " >> \
$(obj).depend ; \
done
endif
###
# Changes in kernel-doc force a rebuild of all documentation
$(BOOKS): $(KERNELDOC)
notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
exit 1
db2xtemplate = db2TYPE -o $(dir $@) $<
xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
# determine which methods are available
ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
use-db2x = db2x
prefer-db2x = db2x
else
use-db2x = notfound
prefer-db2x = $(use-xmlto)
endif
ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found)
use-xmlto = xmlto
prefer-xmlto = xmlto
else
use-xmlto = notfound
prefer-xmlto = $(use-db2x)
endif
# the commands, generated from the chosen template
quiet_cmd_db2ps = PS $@
cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
%.ps : %.xml
$(call cmd_db2ps)
quiet_cmd_db2pdf = PDF $@
cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
%.pdf : %.xml
$(call cmd_db2pdf)
index = index.html
main_idx = $(index)
build_main_index = rm -rf $(main_idx); \
echo '<h1>U-Boot Bootloader HTML Documentation</h1>' >> $(main_idx) && \
echo '<h2>U-Boot Version: $(U_BOOT_VERSION)</h2>' >> $(main_idx) && \
cat $(HTML) >> $(main_idx)
# To work around bug [1] in docbook-xsl-stylesheets 1.76.1 , generate only html
# docs instead of xhtml with xmlto.
# [1] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=654338
quiet_cmd_db2html = HTML $@
cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
$(patsubst %.html,%,$(notdir $@))</a><p>' > $@
%.html: %.xml
@(which xmlto > /dev/null 2>&1) || \
(echo "*** You need to install xmlto ***"; \
exit 1)
@rm -rf $@ $(patsubst %.html,%,$@)
$(call cmd_db2html)
@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
quiet_cmd_db2man = MAN $@
cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi
%.9 : %.xml
@(which xmlto > /dev/null 2>&1) || \
(echo "*** You need to install xmlto ***"; \
exit 1)
$(Q)mkdir -p $(obj)man
$(call cmd_db2man)
@touch $@
###
# Rules to generate postscripts and PNG images from .fig format files
quiet_cmd_fig2eps = FIG2EPS $@
cmd_fig2eps = fig2dev -Leps $< $@
%.eps: %.fig
@(which fig2dev > /dev/null 2>&1) || \
(echo "*** You need to install transfig ***"; \
exit 1)
$(call cmd_fig2eps)
quiet_cmd_fig2png = FIG2PNG $@
cmd_fig2png = fig2dev -Lpng $< $@
%.png: %.fig
@(which fig2dev > /dev/null 2>&1) || \
(echo "*** You need to install transfig ***"; \
exit 1)
$(call cmd_fig2png)
###
# Rule to convert a .c file to inline XML documentation
gen_xml = :
quiet_gen_xml = echo ' GEN $@'
silent_gen_xml = :
%.xml: %.c
@$($(quiet)gen_xml)
@( \
echo "<programlisting>"; \
expand --tabs=8 < $< | \
sed -e "s/&/\\&amp;/g" \
-e "s/</\\&lt;/g" \
-e "s/>/\\&gt;/g"; \
echo "</programlisting>") > $@
###
# Help targets as used by the top-level makefile
dochelp:
@echo ' U-Boot bootloader internal documentation in different formats:'
@echo ' htmldocs - HTML'
@echo ' pdfdocs - PDF'
@echo ' psdocs - Postscript'
@echo ' xmldocs - XML DocBook'
@echo ' mandocs - man pages'
@echo ' installmandocs - install man pages generated by mandocs'
@echo ' cleandocs - clean all generated DocBook files'
###
# Temporary files left by various tools
clean-files := $(DOCBOOKS) \
$(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
$(patsubst %.xml, %.aux, $(DOCBOOKS)) \
$(patsubst %.xml, %.tex, $(DOCBOOKS)) \
$(patsubst %.xml, %.log, $(DOCBOOKS)) \
$(patsubst %.xml, %.out, $(DOCBOOKS)) \
$(patsubst %.xml, %.ps, $(DOCBOOKS)) \
$(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
$(patsubst %.xml, %.html, $(DOCBOOKS)) \
$(patsubst %.xml, %.9, $(DOCBOOKS)) \
$(index)
clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
cleandocs:
@rm -f $(obj).depend
@$(Q)rm -f $(call objectify, $(clean-files))
@$(Q)rm -rf $(call objectify, $(clean-dirs))
# Declare the contents of the .PHONY variable as phony. We keep that
# information in a variable se we can use it in if_changed and friends.
.PHONY: $(PHONY)

View file

@ -0,0 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
<param name="chunk.quietly">1</param>
<param name="funcsynopsis.style">ansi</param>
<param name="funcsynopsis.tabular.threshold">80</param>
<param name="callout.graphics">0</param>
<!-- <param name="paper.type">A4</param> -->
<param name="generate.section.toc.level">2</param>
<param name="use.id.as.filename">1</param>
</stylesheet>

1
tools/.gitignore vendored
View file

@ -17,3 +17,4 @@
/env/fw_printenv
/gdb/gdbcont
/gdb/gdbsend
/kernel-doc/docproc

View file

@ -21,7 +21,7 @@
# MA 02111-1307 USA
#
TOOLSUBDIRS =
TOOLSUBDIRS = kernel-doc
#
# Include this after HOSTOS HOSTARCH check

38
tools/kernel-doc/Makefile Normal file
View file

@ -0,0 +1,38 @@
#
# Copyright (C) 2012 Marek Vasut <marex@denx.de>
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License as
# published by the Free Software Foundation; either version 2 of
# the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston,
# MA 02111-1307 USA
#
include $(TOPDIR)/config.mk
all: $(obj)docproc
$(obj)docproc: docproc.c
$(HOSTCC) $(HOSTCFLAGS) $(HOSTLDFLAGS) -o $@ $^
$(HOSTSTRIP) $@
clean:
rm -rf docproc
#########################################################################
# defines $(obj).depend target
include $(SRCTREE)/rules.mk
sinclude $(obj).depend
#########################################################################

576
tools/kernel-doc/docproc.c Normal file
View file

@ -0,0 +1,576 @@
/*
* docproc is a simple preprocessor for the template files
* used as placeholders for the kernel internal documentation.
* docproc is used for documentation-frontend and
* dependency-generator.
* The two usages have in common that they require
* some knowledge of the .tmpl syntax, therefore they
* are kept together.
*
* documentation-frontend
* Scans the template file and call kernel-doc for
* all occurrences of ![EIF]file
* Beforehand each referenced file is scanned for
* any symbols that are exported via these macros:
* EXPORT_SYMBOL(), EXPORT_SYMBOL_GPL(), &
* EXPORT_SYMBOL_GPL_FUTURE()
* This is used to create proper -function and
* -nofunction arguments in calls to kernel-doc.
* Usage: docproc doc file.tmpl
*
* dependency-generator:
* Scans the template file and list all files
* referenced in a format recognized by make.
* Usage: docproc depend file.tmpl
* Writes dependency information to stdout
* in the following format:
* file.tmpl src.c src2.c
* The filenames are obtained from the following constructs:
* !Efilename
* !Ifilename
* !Dfilename
* !Ffilename
* !Pfilename
*
*/
#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include <unistd.h>
#include <limits.h>
#include <errno.h>
#include <sys/types.h>
#include <sys/wait.h>
/* exitstatus is used to keep track of any failing calls to kernel-doc,
* but execution continues. */
int exitstatus = 0;
typedef void DFL(char *);
DFL *defaultline;
typedef void FILEONLY(char * file);
FILEONLY *internalfunctions;
FILEONLY *externalfunctions;
FILEONLY *symbolsonly;
FILEONLY *findall;
typedef void FILELINE(char * file, char * line);
FILELINE * singlefunctions;
FILELINE * entity_system;
FILELINE * docsection;
#define MAXLINESZ 2048
#define MAXFILES 250
#define KERNELDOCPATH "tools/kernel-doc/"
#define KERNELDOC "kernel-doc"
#define DOCBOOK "-docbook"
#define LIST "-list"
#define FUNCTION "-function"
#define NOFUNCTION "-nofunction"
#define NODOCSECTIONS "-no-doc-sections"
static char *srctree, *kernsrctree;
static char **all_list = NULL;
static int all_list_len = 0;
static void consume_symbol(const char *sym)
{
int i;
for (i = 0; i < all_list_len; i++) {
if (!all_list[i])
continue;
if (strcmp(sym, all_list[i]))
continue;
all_list[i] = NULL;
break;
}
}
static void usage (void)
{
fprintf(stderr, "Usage: docproc {doc|depend} file\n");
fprintf(stderr, "Input is read from file.tmpl. Output is sent to stdout\n");
fprintf(stderr, "doc: frontend when generating kernel documentation\n");
fprintf(stderr, "depend: generate list of files referenced within file\n");
fprintf(stderr, "Environment variable SRCTREE: absolute path to sources.\n");
fprintf(stderr, " KBUILD_SRC: absolute path to kernel source tree.\n");
}
/*
* Execute kernel-doc with parameters given in svec
*/
static void exec_kernel_doc(char **svec)
{
pid_t pid;
int ret;
char real_filename[PATH_MAX + 1];
/* Make sure output generated so far are flushed */
fflush(stdout);
switch (pid=fork()) {
case -1:
perror("fork");
exit(1);
case 0:
memset(real_filename, 0, sizeof(real_filename));
strncat(real_filename, kernsrctree, PATH_MAX);
strncat(real_filename, "/" KERNELDOCPATH KERNELDOC,
PATH_MAX - strlen(real_filename));
execvp(real_filename, svec);
fprintf(stderr, "exec ");
perror(real_filename);
exit(1);
default:
waitpid(pid, &ret ,0);
}
if (WIFEXITED(ret))
exitstatus |= WEXITSTATUS(ret);
else
exitstatus = 0xff;
}
/* Types used to create list of all exported symbols in a number of files */
struct symbols
{
char *name;
};
struct symfile
{
char *filename;
struct symbols *symbollist;
int symbolcnt;
};
struct symfile symfilelist[MAXFILES];
int symfilecnt = 0;
static void add_new_symbol(struct symfile *sym, char * symname)
{
sym->symbollist =
realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *));
sym->symbollist[sym->symbolcnt++].name = strdup(symname);
}
/* Add a filename to the list */
static struct symfile * add_new_file(char * filename)
{
symfilelist[symfilecnt++].filename = strdup(filename);
return &symfilelist[symfilecnt - 1];
}
/* Check if file already are present in the list */
static struct symfile * filename_exist(char * filename)
{
int i;
for (i=0; i < symfilecnt; i++)
if (strcmp(symfilelist[i].filename, filename) == 0)
return &symfilelist[i];
return NULL;
}
/*
* List all files referenced within the template file.
* Files are separated by tabs.
*/
static void adddep(char * file) { printf("\t%s", file); }
static void adddep2(char * file, char * line) { line = line; adddep(file); }
static void noaction(char * line) { line = line; }
static void noaction2(char * file, char * line) { file = file; line = line; }
/* Echo the line without further action */
static void printline(char * line) { printf("%s", line); }
/*
* Find all symbols in filename that are exported with EXPORT_SYMBOL &
* EXPORT_SYMBOL_GPL (& EXPORT_SYMBOL_GPL_FUTURE implicitly).
* All symbols located are stored in symfilelist.
*/
static void find_export_symbols(char * filename)
{
FILE * fp;
struct symfile *sym;
char line[MAXLINESZ];
if (filename_exist(filename) == NULL) {
char real_filename[PATH_MAX + 1];
memset(real_filename, 0, sizeof(real_filename));
strncat(real_filename, srctree, PATH_MAX);
strncat(real_filename, "/", PATH_MAX - strlen(real_filename));
strncat(real_filename, filename,
PATH_MAX - strlen(real_filename));
sym = add_new_file(filename);
fp = fopen(real_filename, "r");
if (fp == NULL) {
fprintf(stderr, "docproc: ");
perror(real_filename);
exit(1);
}
while (fgets(line, MAXLINESZ, fp)) {
char *p;
char *e;
if (((p = strstr(line, "EXPORT_SYMBOL_GPL")) != NULL) ||
((p = strstr(line, "EXPORT_SYMBOL")) != NULL)) {
/* Skip EXPORT_SYMBOL{_GPL} */
while (isalnum(*p) || *p == '_')
p++;
/* Remove parentheses & additional whitespace */
while (isspace(*p))
p++;
if (*p != '(')
continue; /* Syntax error? */
else
p++;
while (isspace(*p))
p++;
e = p;
while (isalnum(*e) || *e == '_')
e++;
*e = '\0';
add_new_symbol(sym, p);
}
}
fclose(fp);
}
}
/*
* Document all external or internal functions in a file.
* Call kernel-doc with following parameters:
* kernel-doc -docbook -nofunction function_name1 filename
* Function names are obtained from all the src files
* by find_export_symbols.
* intfunc uses -nofunction
* extfunc uses -function
*/
static void docfunctions(char * filename, char * type)
{
int i,j;
int symcnt = 0;
int idx = 0;
char **vec;
for (i=0; i <= symfilecnt; i++)
symcnt += symfilelist[i].symbolcnt;
vec = malloc((2 + 2 * symcnt + 3) * sizeof(char *));
if (vec == NULL) {
perror("docproc: ");
exit(1);
}
vec[idx++] = KERNELDOC;
vec[idx++] = DOCBOOK;
vec[idx++] = NODOCSECTIONS;
for (i=0; i < symfilecnt; i++) {
struct symfile * sym = &symfilelist[i];
for (j=0; j < sym->symbolcnt; j++) {
vec[idx++] = type;
consume_symbol(sym->symbollist[j].name);
vec[idx++] = sym->symbollist[j].name;
}
}
vec[idx++] = filename;
vec[idx] = NULL;
printf("<!-- %s -->\n", filename);
exec_kernel_doc(vec);
fflush(stdout);
free(vec);
}
static void intfunc(char * filename) { docfunctions(filename, NOFUNCTION); }
static void extfunc(char * filename) { docfunctions(filename, FUNCTION); }
/*
* Document specific function(s) in a file.
* Call kernel-doc with the following parameters:
* kernel-doc -docbook -function function1 [-function function2]
*/
static void singfunc(char * filename, char * line)
{
char *vec[200]; /* Enough for specific functions */
int i, idx = 0;
int startofsym = 1;
vec[idx++] = KERNELDOC;
vec[idx++] = DOCBOOK;
/* Split line up in individual parameters preceded by FUNCTION */
for (i=0; line[i]; i++) {
if (isspace(line[i])) {
line[i] = '\0';
startofsym = 1;
continue;
}
if (startofsym) {
startofsym = 0;
vec[idx++] = FUNCTION;
vec[idx++] = &line[i];
}
}
for (i = 0; i < idx; i++) {
if (strcmp(vec[i], FUNCTION))
continue;
consume_symbol(vec[i + 1]);
}
vec[idx++] = filename;
vec[idx] = NULL;
exec_kernel_doc(vec);
}
/*
* Insert specific documentation section from a file.
* Call kernel-doc with the following parameters:
* kernel-doc -docbook -function "doc section" filename
*/
static void docsect(char *filename, char *line)
{
char *vec[6]; /* kerneldoc -docbook -function "section" file NULL */
char *s;
for (s = line; *s; s++)
if (*s == '\n')
*s = '\0';
if (asprintf(&s, "DOC: %s", line) < 0) {
perror("asprintf");
exit(1);
}
consume_symbol(s);
free(s);
vec[0] = KERNELDOC;
vec[1] = DOCBOOK;
vec[2] = FUNCTION;
vec[3] = line;
vec[4] = filename;
vec[5] = NULL;
exec_kernel_doc(vec);
}
static void find_all_symbols(char *filename)
{
char *vec[4]; /* kerneldoc -list file NULL */
pid_t pid;
int ret, i, count, start;
char real_filename[PATH_MAX + 1];
int pipefd[2];
char *data, *str;
size_t data_len = 0;
vec[0] = KERNELDOC;
vec[1] = LIST;
vec[2] = filename;
vec[3] = NULL;
if (pipe(pipefd)) {
perror("pipe");
exit(1);
}
switch (pid=fork()) {
case -1:
perror("fork");
exit(1);
case 0:
close(pipefd[0]);
dup2(pipefd[1], 1);
memset(real_filename, 0, sizeof(real_filename));
strncat(real_filename, kernsrctree, PATH_MAX);
strncat(real_filename, "/" KERNELDOCPATH KERNELDOC,
PATH_MAX - strlen(real_filename));
execvp(real_filename, vec);
fprintf(stderr, "exec ");
perror(real_filename);
exit(1);
default:
close(pipefd[1]);
data = malloc(4096);
do {
while ((ret = read(pipefd[0],
data + data_len,
4096)) > 0) {
data_len += ret;
data = realloc(data, data_len + 4096);
}
} while (ret == -EAGAIN);
if (ret != 0) {
perror("read");
exit(1);
}
waitpid(pid, &ret ,0);
}
if (WIFEXITED(ret))
exitstatus |= WEXITSTATUS(ret);
else
exitstatus = 0xff;
count = 0;
/* poor man's strtok, but with counting */
for (i = 0; i < data_len; i++) {
if (data[i] == '\n') {
count++;
data[i] = '\0';
}
}
start = all_list_len;
all_list_len += count;
all_list = realloc(all_list, sizeof(char *) * all_list_len);
str = data;
for (i = 0; i < data_len && start != all_list_len; i++) {
if (data[i] == '\0') {
all_list[start] = str;
str = data + i + 1;
start++;
}
}
}
/*
* Parse file, calling action specific functions for:
* 1) Lines containing !E
* 2) Lines containing !I
* 3) Lines containing !D
* 4) Lines containing !F
* 5) Lines containing !P
* 6) Lines containing !C
* 7) Default lines - lines not matching the above
*/
static void parse_file(FILE *infile)
{
char line[MAXLINESZ];
char * s;
while (fgets(line, MAXLINESZ, infile)) {
if (line[0] == '!') {
s = line + 2;
switch (line[1]) {
case 'E':
while (*s && !isspace(*s)) s++;
*s = '\0';
externalfunctions(line+2);
break;
case 'I':
while (*s && !isspace(*s)) s++;
*s = '\0';
internalfunctions(line+2);
break;
case 'D':
while (*s && !isspace(*s)) s++;
*s = '\0';
symbolsonly(line+2);
break;
case 'F':
/* filename */
while (*s && !isspace(*s)) s++;
*s++ = '\0';
/* function names */
while (isspace(*s))
s++;
singlefunctions(line +2, s);
break;
case 'P':
/* filename */
while (*s && !isspace(*s)) s++;
*s++ = '\0';
/* DOC: section name */
while (isspace(*s))
s++;
docsection(line + 2, s);
break;
case 'C':
while (*s && !isspace(*s)) s++;
*s = '\0';
if (findall)
findall(line+2);
break;
default:
defaultline(line);
}
} else {
defaultline(line);
}
}
fflush(stdout);
}
int main(int argc, char *argv[])
{
FILE * infile;
int i;
srctree = getenv("SRCTREE");
if (!srctree)
srctree = getcwd(NULL, 0);
kernsrctree = getenv("KBUILD_SRC");
if (!kernsrctree || !*kernsrctree)
kernsrctree = srctree;
if (argc != 3) {
usage();
exit(1);
}
/* Open file, exit on error */
infile = fopen(argv[2], "r");
if (infile == NULL) {
fprintf(stderr, "docproc: ");
perror(argv[2]);
exit(2);
}
if (strcmp("doc", argv[1]) == 0) {
/* Need to do this in two passes.
* First pass is used to collect all symbols exported
* in the various files;
* Second pass generate the documentation.
* This is required because some functions are declared
* and exported in different files :-((
*/
/* Collect symbols */
defaultline = noaction;
internalfunctions = find_export_symbols;
externalfunctions = find_export_symbols;
symbolsonly = find_export_symbols;
singlefunctions = noaction2;
docsection = noaction2;
findall = find_all_symbols;
parse_file(infile);
/* Rewind to start from beginning of file again */
fseek(infile, 0, SEEK_SET);
defaultline = printline;
internalfunctions = intfunc;
externalfunctions = extfunc;
symbolsonly = printline;
singlefunctions = singfunc;
docsection = docsect;
findall = NULL;
parse_file(infile);
for (i = 0; i < all_list_len; i++) {
if (!all_list[i])
continue;
fprintf(stderr, "Warning: didn't use docs for %s\n",
all_list[i]);
}
} else if (strcmp("depend", argv[1]) == 0) {
/* Create first part of dependency chain
* file.tmpl */
printf("%s\t", argv[2]);
defaultline = noaction;
internalfunctions = adddep;
externalfunctions = adddep;
symbolsonly = adddep;
singlefunctions = adddep2;
docsection = adddep2;
findall = adddep;
parse_file(infile);
printf("\n");
} else {
fprintf(stderr, "Unknown option: %s\n", argv[1]);
exit(1);
}
fclose(infile);
fflush(stdout);
return exitstatus;
}

2554
tools/kernel-doc/kernel-doc Executable file

File diff suppressed because it is too large Load diff