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
Tom Rini
parent
c50204a517
commit
30ff89189b
7
Makefile
7
Makefile
@ -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
15
doc/DocBook/.gitignore
vendored
Normal 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
229
doc/DocBook/Makefile
Normal 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/&/\\&/g" \
|
||||
-e "s/</\\</g" \
|
||||
-e "s/>/\\>/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)
|
||||
10
doc/DocBook/stylesheet.xsl
Normal file
10
doc/DocBook/stylesheet.xsl
Normal 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
1
tools/.gitignore
vendored
@ -17,3 +17,4 @@
|
||||
/env/fw_printenv
|
||||
/gdb/gdbcont
|
||||
/gdb/gdbsend
|
||||
/kernel-doc/docproc
|
||||
|
||||
@ -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
38
tools/kernel-doc/Makefile
Normal 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
576
tools/kernel-doc/docproc.c
Normal 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
2554
tools/kernel-doc/kernel-doc
Executable file
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user