doc: Replace DocBook with sphinx-based docs
The Linux kernel moved to sphinx-based documentation and got rid of the DocBook based documentation quite a while ago. Hence, the DocBook documentation for U-Boot should be converted as well. To achieve this, import the necessary files from Linux v4.17, and convert the current DocBook documentation (three files altogether) to sphinx/reStructuredText. For now, all old DocBook documentation was merged into a single handbook, tentatively named "U-Boot Hacker Manual". For some source files, the documentation style was changed to comply with kernel-doc; no functional changes were applied. Signed-off-by: Mario Six <mario.six@gdsys.cc>
This commit is contained in:
Mario Six
Tom Rini
parent
5448ff33f2
commit
78a88f7930
2
Documentation/.gitignore
vendored
Normal file
2
Documentation/.gitignore
vendored
Normal file
@ -0,0 +1,2 @@
|
||||
output
|
||||
*.pyc
|
||||
124
Documentation/Makefile
Normal file
124
Documentation/Makefile
Normal file
@ -0,0 +1,124 @@
|
||||
# -*- makefile -*-
|
||||
# Makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
subdir-y :=
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXBUILD = sphinx-build
|
||||
SPHINXOPTS =
|
||||
SPHINXDIRS = .
|
||||
_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py))
|
||||
SPHINX_CONF = conf.py
|
||||
PAPER =
|
||||
BUILDDIR = $(obj)/output
|
||||
PDFLATEX = xelatex
|
||||
LATEXOPTS = -interaction=batchmode
|
||||
|
||||
# User-friendly check for sphinx-build
|
||||
HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)
|
||||
|
||||
ifeq ($(HAVE_SPHINX),0)
|
||||
|
||||
.DEFAULT:
|
||||
$(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.)
|
||||
@echo
|
||||
@./scripts/sphinx-pre-install
|
||||
@echo " SKIP Sphinx $@ target."
|
||||
|
||||
else # HAVE_SPHINX
|
||||
|
||||
# User-friendly check for pdflatex
|
||||
HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
|
||||
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||
PAPEROPT_letter = -D latex_paper_size=letter
|
||||
KERNELDOC = $(srctree)/scripts/kernel-doc
|
||||
KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
|
||||
ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
|
||||
# the i18n builder cannot share the environment and doctrees with the others
|
||||
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
|
||||
# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
|
||||
loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
|
||||
|
||||
# $2 sphinx builder e.g. "html"
|
||||
# $3 name of the build subfolder / e.g. "media", used as:
|
||||
# * dest folder relative to $(BUILDDIR) and
|
||||
# * cache folder relative to $(BUILDDIR)/.doctrees
|
||||
# $4 dest subfolder e.g. "man" for man pages at media/man
|
||||
# $5 reST source folder relative to $(srctree)/$(src),
|
||||
# e.g. "media" for the linux-tv book-set at ./Documentation/media
|
||||
|
||||
quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
|
||||
cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2 && \
|
||||
PYTHONDONTWRITEBYTECODE=1 \
|
||||
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
|
||||
$(SPHINXBUILD) \
|
||||
-b $2 \
|
||||
-c $(abspath $(srctree)/$(src)) \
|
||||
-d $(abspath $(BUILDDIR)/.doctrees/$3) \
|
||||
-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
|
||||
$(ALLSPHINXOPTS) \
|
||||
$(abspath $(srctree)/$(src)/$5) \
|
||||
$(abspath $(BUILDDIR)/$3/$4)
|
||||
|
||||
htmldocs:
|
||||
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
|
||||
|
||||
linkcheckdocs:
|
||||
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
|
||||
|
||||
latexdocs:
|
||||
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
|
||||
|
||||
ifeq ($(HAVE_PDFLATEX),0)
|
||||
|
||||
pdfdocs:
|
||||
$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
|
||||
@echo " SKIP Sphinx $@ target."
|
||||
|
||||
else # HAVE_PDFLATEX
|
||||
|
||||
pdfdocs: latexdocs
|
||||
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
|
||||
|
||||
endif # HAVE_PDFLATEX
|
||||
|
||||
epubdocs:
|
||||
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
|
||||
|
||||
xmldocs:
|
||||
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
|
||||
|
||||
endif # HAVE_SPHINX
|
||||
|
||||
# The following targets are independent of HAVE_SPHINX, and the rules should
|
||||
# work or silently pass without Sphinx.
|
||||
|
||||
refcheckdocs:
|
||||
$(Q)cd $(srctree);scripts/documentation-file-ref-check
|
||||
|
||||
cleandocs:
|
||||
$(Q)rm -rf $(BUILDDIR)
|
||||
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
|
||||
|
||||
dochelp:
|
||||
@echo ' Linux kernel internal documentation in different formats from ReST:'
|
||||
@echo ' htmldocs - HTML'
|
||||
@echo ' latexdocs - LaTeX'
|
||||
@echo ' pdfdocs - PDF'
|
||||
@echo ' epubdocs - EPUB'
|
||||
@echo ' xmldocs - XML'
|
||||
@echo ' linkcheckdocs - check for broken external links (will connect to external hosts)'
|
||||
@echo ' refcheckdocs - check for references to non-existing files under Documentation'
|
||||
@echo ' cleandocs - clean all generated files'
|
||||
@echo
|
||||
@echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
|
||||
@echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)'
|
||||
@echo
|
||||
@echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
|
||||
@echo ' configuration. This is e.g. useful to build with nit-picking config.'
|
||||
@echo
|
||||
@echo ' Default location for the generated documents is Documentation/output'
|
||||
528
Documentation/conf.py
Normal file
528
Documentation/conf.py
Normal file
@ -0,0 +1,528 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# The U-Boot documentation build configuration file, created by
|
||||
# sphinx-quickstart on Fri Feb 12 13:51:46 2016.
|
||||
#
|
||||
# This file is execfile()d with the current directory set to its
|
||||
# containing dir.
|
||||
#
|
||||
# Note that not all possible configuration values are present in this
|
||||
# autogenerated file.
|
||||
#
|
||||
# All configuration values have a default; values that are commented out
|
||||
# serve to show the default.
|
||||
|
||||
import sys
|
||||
import os
|
||||
import sphinx
|
||||
|
||||
# Get Sphinx version
|
||||
major, minor, patch = sphinx.version_info[:3]
|
||||
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
sys.path.insert(0, os.path.abspath('sphinx'))
|
||||
from load_config import loadConfig
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
needs_sphinx = '1.3'
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure']
|
||||
|
||||
# The name of the math extension changed on Sphinx 1.4
|
||||
if major == 1 and minor > 3:
|
||||
extensions.append("sphinx.ext.imgmath")
|
||||
else:
|
||||
extensions.append("sphinx.ext.pngmath")
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
# source_suffix = ['.rst', '.md']
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The encoding of source files.
|
||||
#source_encoding = 'utf-8-sig'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = 'Das U-Boot'
|
||||
copyright = 'The U-Boot development community'
|
||||
author = 'The U-Boot development community'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
# built documents.
|
||||
#
|
||||
# In a normal build, version and release are are set to KERNELVERSION and
|
||||
# KERNELRELEASE, respectively, from the Makefile via Sphinx command line
|
||||
# arguments.
|
||||
#
|
||||
# The following code tries to extract the information by reading the Makefile,
|
||||
# when Sphinx is run directly (e.g. by Read the Docs).
|
||||
try:
|
||||
makefile_version = None
|
||||
makefile_patchlevel = None
|
||||
for line in open('../Makefile'):
|
||||
key, val = [x.strip() for x in line.split('=', 2)]
|
||||
if key == 'VERSION':
|
||||
makefile_version = val
|
||||
elif key == 'PATCHLEVEL':
|
||||
makefile_patchlevel = val
|
||||
if makefile_version and makefile_patchlevel:
|
||||
break
|
||||
except:
|
||||
pass
|
||||
finally:
|
||||
if makefile_version and makefile_patchlevel:
|
||||
version = release = makefile_version + '.' + makefile_patchlevel
|
||||
else:
|
||||
version = release = "unknown version"
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = None
|
||||
|
||||
# There are two options for replacing |today|: either, you set today to some
|
||||
# non-false value, then it is used:
|
||||
#today = ''
|
||||
# Else, today_fmt is used as the format for a strftime call.
|
||||
#today_fmt = '%B %d, %Y'
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
exclude_patterns = ['output']
|
||||
|
||||
# The reST default role (used for this markup: `text`) to use for all
|
||||
# documents.
|
||||
#default_role = None
|
||||
|
||||
# If true, '()' will be appended to :func: etc. cross-reference text.
|
||||
#add_function_parentheses = True
|
||||
|
||||
# If true, the current module name will be prepended to all description
|
||||
# unit titles (such as .. function::).
|
||||
#add_module_names = True
|
||||
|
||||
# If true, sectionauthor and moduleauthor directives will be shown in the
|
||||
# output. They are ignored by default.
|
||||
#show_authors = False
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
# A list of ignored prefixes for module index sorting.
|
||||
#modindex_common_prefix = []
|
||||
|
||||
# If true, keep warnings as "system message" paragraphs in the built documents.
|
||||
#keep_warnings = False
|
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||
todo_include_todos = False
|
||||
|
||||
primary_domain = 'c'
|
||||
highlight_language = 'none'
|
||||
|
||||
# -- Options for HTML output ----------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
|
||||
# The Read the Docs theme is available from
|
||||
# - https://github.com/snide/sphinx_rtd_theme
|
||||
# - https://pypi.python.org/pypi/sphinx_rtd_theme
|
||||
# - python-sphinx-rtd-theme package (on Debian)
|
||||
try:
|
||||
import sphinx_rtd_theme
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||
except ImportError:
|
||||
sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.\n')
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
#html_theme_options = {}
|
||||
|
||||
# Add any paths that contain custom themes here, relative to this directory.
|
||||
#html_theme_path = []
|
||||
|
||||
# The name for this set of Sphinx documents. If None, it defaults to
|
||||
# "<project> v<release> documentation".
|
||||
#html_title = None
|
||||
|
||||
# A shorter title for the navigation bar. Default is the same as html_title.
|
||||
#html_short_title = None
|
||||
|
||||
# The name of an image file (relative to this directory) to place at the top
|
||||
# of the sidebar.
|
||||
#html_logo = None
|
||||
|
||||
# The name of an image file (within the static path) to use as favicon of the
|
||||
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
|
||||
# pixels large.
|
||||
#html_favicon = None
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
|
||||
html_static_path = ['sphinx-static']
|
||||
|
||||
html_context = {
|
||||
'css_files': [
|
||||
'_static/theme_overrides.css',
|
||||
],
|
||||
}
|
||||
|
||||
# Add any extra paths that contain custom files (such as robots.txt or
|
||||
# .htaccess) here, relative to this directory. These files are copied
|
||||
# directly to the root of the documentation.
|
||||
#html_extra_path = []
|
||||
|
||||
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
|
||||
# using the given strftime format.
|
||||
#html_last_updated_fmt = '%b %d, %Y'
|
||||
|
||||
# If true, SmartyPants will be used to convert quotes and dashes to
|
||||
# typographically correct entities.
|
||||
#html_use_smartypants = True
|
||||
|
||||
# Custom sidebar templates, maps document names to template names.
|
||||
#html_sidebars = {}
|
||||
|
||||
# Additional templates that should be rendered to pages, maps page names to
|
||||
# template names.
|
||||
#html_additional_pages = {}
|
||||
|
||||
# If false, no module index is generated.
|
||||
#html_domain_indices = True
|
||||
|
||||
# If false, no index is generated.
|
||||
#html_use_index = True
|
||||
|
||||
# If true, the index is split into individual pages for each letter.
|
||||
#html_split_index = False
|
||||
|
||||
# If true, links to the reST sources are added to the pages.
|
||||
#html_show_sourcelink = True
|
||||
|
||||
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
|
||||
#html_show_sphinx = True
|
||||
|
||||
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
|
||||
#html_show_copyright = True
|
||||
|
||||
# If true, an OpenSearch description file will be output, and all pages will
|
||||
# contain a <link> tag referring to it. The value of this option must be the
|
||||
# base URL from which the finished HTML is served.
|
||||
#html_use_opensearch = ''
|
||||
|
||||
# This is the file name suffix for HTML files (e.g. ".xhtml").
|
||||
#html_file_suffix = None
|
||||
|
||||
# Language to be used for generating the HTML full-text search index.
|
||||
# Sphinx supports the following languages:
|
||||
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
|
||||
# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
|
||||
#html_search_language = 'en'
|
||||
|
||||
# A dictionary with options for the search language support, empty by default.
|
||||
# Now only 'ja' uses this config value
|
||||
#html_search_options = {'type': 'default'}
|
||||
|
||||
# The name of a javascript file (relative to the configuration directory) that
|
||||
# implements a search results scorer. If empty, the default will be used.
|
||||
#html_search_scorer = 'scorer.js'
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'TheUBootdoc'
|
||||
|
||||
# -- Options for LaTeX output ---------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
'papersize': 'a4paper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
'pointsize': '8pt',
|
||||
|
||||
# Latex figure (float) alignment
|
||||
#'figure_align': 'htbp',
|
||||
|
||||
# Don't mangle with UTF-8 chars
|
||||
'inputenc': '',
|
||||
'utf8extra': '',
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
'preamble': '''
|
||||
% Use some font with UTF-8 support with XeLaTeX
|
||||
\\usepackage{fontspec}
|
||||
\\setsansfont{DejaVu Serif}
|
||||
\\setromanfont{DejaVu Sans}
|
||||
\\setmonofont{DejaVu Sans Mono}
|
||||
|
||||
'''
|
||||
}
|
||||
|
||||
# Fix reference escape troubles with Sphinx 1.4.x
|
||||
if major == 1 and minor > 3:
|
||||
latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'
|
||||
|
||||
if major == 1 and minor <= 4:
|
||||
latex_elements['preamble'] += '\\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}'
|
||||
elif major == 1 and (minor > 5 or (minor == 5 and patch >= 3)):
|
||||
latex_elements['sphinxsetup'] = 'hmargin=0.5in, vmargin=1in'
|
||||
latex_elements['preamble'] += '\\fvset{fontsize=auto}\n'
|
||||
|
||||
# Customize notice background colors on Sphinx < 1.6:
|
||||
if major == 1 and minor < 6:
|
||||
latex_elements['preamble'] += '''
|
||||
\\usepackage{ifthen}
|
||||
|
||||
% Put notes in color and let them be inside a table
|
||||
\\definecolor{NoteColor}{RGB}{204,255,255}
|
||||
\\definecolor{WarningColor}{RGB}{255,204,204}
|
||||
\\definecolor{AttentionColor}{RGB}{255,255,204}
|
||||
\\definecolor{ImportantColor}{RGB}{192,255,204}
|
||||
\\definecolor{OtherColor}{RGB}{204,204,204}
|
||||
\\newlength{\\mynoticelength}
|
||||
\\makeatletter\\newenvironment{coloredbox}[1]{%
|
||||
\\setlength{\\fboxrule}{1pt}
|
||||
\\setlength{\\fboxsep}{7pt}
|
||||
\\setlength{\\mynoticelength}{\\linewidth}
|
||||
\\addtolength{\\mynoticelength}{-2\\fboxsep}
|
||||
\\addtolength{\\mynoticelength}{-2\\fboxrule}
|
||||
\\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\mynoticelength}}{\\end{minipage}\\end{lrbox}%
|
||||
\\ifthenelse%
|
||||
{\\equal{\\py@noticetype}{note}}%
|
||||
{\\colorbox{NoteColor}{\\usebox{\\@tempboxa}}}%
|
||||
{%
|
||||
\\ifthenelse%
|
||||
{\\equal{\\py@noticetype}{warning}}%
|
||||
{\\colorbox{WarningColor}{\\usebox{\\@tempboxa}}}%
|
||||
{%
|
||||
\\ifthenelse%
|
||||
{\\equal{\\py@noticetype}{attention}}%
|
||||
{\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}%
|
||||
{%
|
||||
\\ifthenelse%
|
||||
{\\equal{\\py@noticetype}{important}}%
|
||||
{\\colorbox{ImportantColor}{\\usebox{\\@tempboxa}}}%
|
||||
{\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
|
||||
}%
|
||||
}%
|
||||
}%
|
||||
}\\makeatother
|
||||
|
||||
\\makeatletter
|
||||
\\renewenvironment{notice}[2]{%
|
||||
\\def\\py@noticetype{#1}
|
||||
\\begin{coloredbox}{#1}
|
||||
\\bf\\it
|
||||
\\par\\strong{#2}
|
||||
\\csname py@noticestart@#1\\endcsname
|
||||
}
|
||||
{
|
||||
\\csname py@noticeend@\\py@noticetype\\endcsname
|
||||
\\end{coloredbox}
|
||||
}
|
||||
\\makeatother
|
||||
|
||||
'''
|
||||
|
||||
# With Sphinx 1.6, it is possible to change the Bg color directly
|
||||
# by using:
|
||||
# \definecolor{sphinxnoteBgColor}{RGB}{204,255,255}
|
||||
# \definecolor{sphinxwarningBgColor}{RGB}{255,204,204}
|
||||
# \definecolor{sphinxattentionBgColor}{RGB}{255,255,204}
|
||||
# \definecolor{sphinximportantBgColor}{RGB}{192,255,204}
|
||||
#
|
||||
# However, it require to use sphinx heavy box with:
|
||||
#
|
||||
# \renewenvironment{sphinxlightbox} {%
|
||||
# \\begin{sphinxheavybox}
|
||||
# }
|
||||
# \\end{sphinxheavybox}
|
||||
# }
|
||||
#
|
||||
# Unfortunately, the implementation is buggy: if a note is inside a
|
||||
# table, it isn't displayed well. So, for now, let's use boring
|
||||
# black and white notes.
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
# Sorted in alphabetical order
|
||||
latex_documents = [
|
||||
('index', 'u-boot-hacker-manual.tex', 'U-Boot Hacker Manual',
|
||||
'The U-Boot development community', 'manual'),
|
||||
]
|
||||
|
||||
# The name of an image file (relative to this directory) to place at the top of
|
||||
# the title page.
|
||||
#latex_logo = None
|
||||
|
||||
# For "manual" documents, if this is true, then toplevel headings are parts,
|
||||
# not chapters.
|
||||
#latex_use_parts = False
|
||||
|
||||
# If true, show page references after internal links.
|
||||
#latex_show_pagerefs = False
|
||||
|
||||
# If true, show URL addresses after external links.
|
||||
#latex_show_urls = False
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
#latex_appendices = []
|
||||
|
||||
# If false, no module index is generated.
|
||||
#latex_domain_indices = True
|
||||
|
||||
|
||||
# -- Options for manual page output ---------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
(master_doc, 'dasuboot', 'The U-Boot Documentation',
|
||||
[author], 1)
|
||||
]
|
||||
|
||||
# If true, show URL addresses after external links.
|
||||
#man_show_urls = False
|
||||
|
||||
|
||||
# -- Options for Texinfo output -------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(master_doc, 'DasUBoot', 'The U-Boot Documentation',
|
||||
author, 'DasUBoot', 'One line description of project.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
#texinfo_appendices = []
|
||||
|
||||
# If false, no module index is generated.
|
||||
#texinfo_domain_indices = True
|
||||
|
||||
# How to display URL addresses: 'footnote', 'no', or 'inline'.
|
||||
#texinfo_show_urls = 'footnote'
|
||||
|
||||
# If true, do not generate a @detailmenu in the "Top" node's menu.
|
||||
#texinfo_no_detailmenu = False
|
||||
|
||||
|
||||
# -- Options for Epub output ----------------------------------------------
|
||||
|
||||
# Bibliographic Dublin Core info.
|
||||
epub_title = project
|
||||
epub_author = author
|
||||
epub_publisher = author
|
||||
epub_copyright = copyright
|
||||
|
||||
# The basename for the epub file. It defaults to the project name.
|
||||
#epub_basename = project
|
||||
|
||||
# The HTML theme for the epub output. Since the default themes are not
|
||||
# optimized for small screen space, using the same theme for HTML and epub
|
||||
# output is usually not wise. This defaults to 'epub', a theme designed to save
|
||||
# visual space.
|
||||
#epub_theme = 'epub'
|
||||
|
||||
# The language of the text. It defaults to the language option
|
||||
# or 'en' if the language is not set.
|
||||
#epub_language = ''
|
||||
|
||||
# The scheme of the identifier. Typical schemes are ISBN or URL.
|
||||
#epub_scheme = ''
|
||||
|
||||
# The unique identifier of the text. This can be a ISBN number
|
||||
# or the project homepage.
|
||||
#epub_identifier = ''
|
||||
|
||||
# A unique identification for the text.
|
||||
#epub_uid = ''
|
||||
|
||||
# A tuple containing the cover image and cover page html template filenames.
|
||||
#epub_cover = ()
|
||||
|
||||
# A sequence of (type, uri, title) tuples for the guide element of content.opf.
|
||||
#epub_guide = ()
|
||||
|
||||
# HTML files that should be inserted before the pages created by sphinx.
|
||||
# The format is a list of tuples containing the path and title.
|
||||
#epub_pre_files = []
|
||||
|
||||
# HTML files that should be inserted after the pages created by sphinx.
|
||||
# The format is a list of tuples containing the path and title.
|
||||
#epub_post_files = []
|
||||
|
||||
# A list of files that should not be packed into the epub file.
|
||||
epub_exclude_files = ['search.html']
|
||||
|
||||
# The depth of the table of contents in toc.ncx.
|
||||
#epub_tocdepth = 3
|
||||
|
||||
# Allow duplicate toc entries.
|
||||
#epub_tocdup = True
|
||||
|
||||
# Choose between 'default' and 'includehidden'.
|
||||
#epub_tocscope = 'default'
|
||||
|
||||
# Fix unsupported image types using the Pillow.
|
||||
#epub_fix_images = False
|
||||
|
||||
# Scale large images.
|
||||
#epub_max_image_width = 0
|
||||
|
||||
# How to display URL addresses: 'footnote', 'no', or 'inline'.
|
||||
#epub_show_urls = 'inline'
|
||||
|
||||
# If false, no index is generated.
|
||||
#epub_use_index = True
|
||||
|
||||
#=======
|
||||
# rst2pdf
|
||||
#
|
||||
# Grouping the document tree into PDF files. List of tuples
|
||||
# (source start file, target name, title, author, options).
|
||||
#
|
||||
# See the Sphinx chapter of http://ralsina.me/static/manual.pdf
|
||||
#
|
||||
# FIXME: Do not add the index file here; the result will be too big. Adding
|
||||
# multiple PDF files here actually tries to get the cross-referencing right
|
||||
# *between* PDF files.
|
||||
pdf_documents = [
|
||||
('uboot-documentation', u'U-Boot', u'U-Boot', u'J. Random Bozo'),
|
||||
]
|
||||
|
||||
# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
|
||||
# the Docs). In a normal build, these are supplied from the Makefile via command
|
||||
# line arguments.
|
||||
kerneldoc_bin = '../scripts/kernel-doc'
|
||||
kerneldoc_srctree = '..'
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# Since loadConfig overwrites settings from the global namespace, it has to be
|
||||
# the last statement in the conf.py file
|
||||
# ------------------------------------------------------------------------------
|
||||
loadConfig(globals())
|
||||
117
Documentation/index.rst
Normal file
117
Documentation/index.rst
Normal file
@ -0,0 +1,117 @@
|
||||
====================
|
||||
U-Boot Hacker Manual
|
||||
====================
|
||||
|
||||
Linker-Generated Arrays
|
||||
=======================
|
||||
|
||||
A linker list is constructed by grouping together linker input
|
||||
sections, each containing one entry of the list. Each input section
|
||||
contains a constant initialized variable which holds the entry's
|
||||
content. Linker list input sections are constructed from the list
|
||||
and entry names, plus a prefix which allows grouping all lists
|
||||
together. Assuming _list and _entry are the list and entry names,
|
||||
then the corresponding input section name is
|
||||
|
||||
::
|
||||
|
||||
.u_boot_list_ + 2_ + @_list + _2_ + @_entry
|
||||
|
||||
and the C variable name is
|
||||
|
||||
::
|
||||
|
||||
_u_boot_list + _2_ + @_list + _2_ + @_entry
|
||||
|
||||
This ensures uniqueness for both input section and C variable name.
|
||||
|
||||
Note that the names differ only in the first character, "." for the
|
||||
section and "_" for the variable, so that the linker cannot confuse
|
||||
section and symbol names. From now on, both names will be referred
|
||||
to as
|
||||
|
||||
::
|
||||
|
||||
%u_boot_list_ + 2_ + @_list + _2_ + @_entry
|
||||
|
||||
Entry variables need never be referred to directly.
|
||||
|
||||
The naming scheme for input sections allows grouping all linker lists
|
||||
into a single linker output section and grouping all entries for a
|
||||
single list.
|
||||
|
||||
Note the two '_2_' constant components in the names: their presence
|
||||
allows putting a start and end symbols around a list, by mapping
|
||||
these symbols to sections names with components "1" (before) and
|
||||
"3" (after) instead of "2" (within).
|
||||
Start and end symbols for a list can generally be defined as
|
||||
|
||||
::
|
||||
|
||||
%u_boot_list_2_ + @_list + _1_...
|
||||
%u_boot_list_2_ + @_list + _3_...
|
||||
|
||||
Start and end symbols for the whole of the linker lists area can be
|
||||
defined as
|
||||
|
||||
::
|
||||
|
||||
%u_boot_list_1_...
|
||||
%u_boot_list_3_...
|
||||
|
||||
Here is an example of the sorted sections which result from a list
|
||||
"array" made up of three entries : "first", "second" and "third",
|
||||
iterated at least once.
|
||||
|
||||
::
|
||||
|
||||
.u_boot_list_2_array_1
|
||||
.u_boot_list_2_array_2_first
|
||||
.u_boot_list_2_array_2_second
|
||||
.u_boot_list_2_array_2_third
|
||||
.u_boot_list_2_array_3
|
||||
|
||||
If lists must be divided into sublists (e.g. for iterating only on
|
||||
part of a list), one can simply give the list a name of the form
|
||||
'outer_2_inner', where 'outer' is the global list name and 'inner'
|
||||
is the sub-list name. Iterators for the whole list should use the
|
||||
global list name ("outer"); iterators for only a sub-list should use
|
||||
the full sub-list name ("outer_2_inner").
|
||||
|
||||
Here is an example of the sections generated from a global list
|
||||
named "drivers", two sub-lists named "i2c" and "pci", and iterators
|
||||
defined for the whole list and each sub-list:
|
||||
|
||||
::
|
||||
|
||||
%u_boot_list_2_drivers_1
|
||||
%u_boot_list_2_drivers_2_i2c_1
|
||||
%u_boot_list_2_drivers_2_i2c_2_first
|
||||
%u_boot_list_2_drivers_2_i2c_2_first
|
||||
%u_boot_list_2_drivers_2_i2c_2_second
|
||||
%u_boot_list_2_drivers_2_i2c_2_third
|
||||
%u_boot_list_2_drivers_2_i2c_3
|
||||
%u_boot_list_2_drivers_2_pci_1
|
||||
%u_boot_list_2_drivers_2_pci_2_first
|
||||
%u_boot_list_2_drivers_2_pci_2_second
|
||||
%u_boot_list_2_drivers_2_pci_2_third
|
||||
%u_boot_list_2_drivers_2_pci_3
|
||||
%u_boot_list_2_drivers_3
|
||||
|
||||
.. kernel-doc:: include/linker_lists.h
|
||||
:internal:
|
||||
|
||||
Serial system
|
||||
=============
|
||||
|
||||
.. kernel-doc:: drivers/serial/serial.c
|
||||
:internal:
|
||||
|
||||
The U-Boot EFI subsystem
|
||||
========================
|
||||
|
||||
Boot services
|
||||
-------------
|
||||
|
||||
.. kernel-doc:: lib/efi_loader/efi_boottime.c
|
||||
:internal:
|
||||
38
Documentation/media/Makefile
Normal file
38
Documentation/media/Makefile
Normal file
@ -0,0 +1,38 @@
|
||||
# Rules to convert a .h file to inline RST documentation
|
||||
|
||||
SRC_DIR=$(srctree)/Documentation/media
|
||||
PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl
|
||||
API = $(srctree)/include
|
||||
|
||||
FILES = linker_lists.h.rst
|
||||
|
||||
TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
|
||||
|
||||
gen_rst = \
|
||||
echo ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions; \
|
||||
${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions
|
||||
|
||||
quiet_gen_rst = echo ' PARSE $(patsubst $(srctree)/%,%,$<)'; \
|
||||
${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions
|
||||
|
||||
silent_gen_rst = ${gen_rst}
|
||||
|
||||
$(BUILDDIR)/linker_lists.h.rst: ${API}/linker_lists.h ${PARSER} $(SRC_DIR)/linker_lists.h.rst.exceptions
|
||||
@$($(quiet)gen_rst)
|
||||
|
||||
# Media build rules
|
||||
|
||||
.PHONY: all html epub xml latex
|
||||
|
||||
all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
|
||||
html: all
|
||||
epub: all
|
||||
xml: all
|
||||
latex: $(IMGPDF) all
|
||||
linkcheck:
|
||||
|
||||
clean:
|
||||
-rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null
|
||||
|
||||
$(BUILDDIR):
|
||||
$(Q)mkdir -p $@
|
||||
0
Documentation/media/linker_lists.h.rst.exceptions
Normal file
0
Documentation/media/linker_lists.h.rst.exceptions
Normal file
89
Documentation/sphinx-static/theme_overrides.css
Normal file
89
Documentation/sphinx-static/theme_overrides.css
Normal file
@ -0,0 +1,89 @@
|
||||
/* -*- coding: utf-8; mode: css -*-
|
||||
*
|
||||
* Sphinx HTML theme customization: read the doc
|
||||
*
|
||||
*/
|
||||
|
||||
/* Interim: Code-blocks with line nos - lines and line numbers don't line up.
|
||||
* see: https://github.com/rtfd/sphinx_rtd_theme/issues/419
|
||||
*/
|
||||
|
||||
div[class^="highlight"] pre {
|
||||
line-height: normal;
|
||||
}
|
||||
.rst-content .highlight > pre {
|
||||
line-height: normal;
|
||||
}
|
||||
|
||||
@media screen {
|
||||
|
||||
/* content column
|
||||
*
|
||||
* RTD theme's default is 800px as max width for the content, but we have
|
||||
* tables with tons of columns, which need the full width of the view-port.
|
||||
*/
|
||||
|
||||
.wy-nav-content{max-width: none; }
|
||||
|
||||
/* table:
|
||||
*
|
||||
* - Sequences of whitespace should collapse into a single whitespace.
|
||||
* - make the overflow auto (scrollbar if needed)
|
||||
* - align caption "left" ("center" is unsuitable on vast tables)
|
||||
*/
|
||||
|
||||
.wy-table-responsive table td { white-space: normal; }
|
||||
.wy-table-responsive { overflow: auto; }
|
||||
.rst-content table.docutils caption { text-align: left; font-size: 100%; }
|
||||
|
||||
/* captions:
|
||||
*
|
||||
* - captions should have 100% (not 85%) font size
|
||||
* - hide the permalink symbol as long as link is not hovered
|
||||
*/
|
||||
|
||||
.toc-title {
|
||||
font-size: 150%;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
caption, .wy-table caption, .rst-content table.field-list caption {
|
||||
font-size: 100%;
|
||||
}
|
||||
caption a.headerlink { opacity: 0; }
|
||||
caption a.headerlink:hover { opacity: 1; }
|
||||
|
||||
/* Menu selection and keystrokes */
|
||||
|
||||
span.menuselection {
|
||||
color: blue;
|
||||
font-family: "Courier New", Courier, monospace
|
||||
}
|
||||
|
||||
code.kbd, code.kbd span {
|
||||
color: white;
|
||||
background-color: darkblue;
|
||||
font-weight: bold;
|
||||
font-family: "Courier New", Courier, monospace
|
||||
}
|
||||
|
||||
/* fix bottom margin of lists items */
|
||||
|
||||
.rst-content .section ul li:last-child, .rst-content .section ul li p:last-child {
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
|
||||
/* inline literal: drop the borderbox, padding and red color */
|
||||
|
||||
code, .rst-content tt, .rst-content code {
|
||||
color: inherit;
|
||||
border: none;
|
||||
padding: unset;
|
||||
background: inherit;
|
||||
font-size: 85%;
|
||||
}
|
||||
|
||||
.rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal {
|
||||
color: inherit;
|
||||
}
|
||||
}
|
||||
165
Documentation/sphinx/cdomain.py
Normal file
165
Documentation/sphinx/cdomain.py
Normal file
@ -0,0 +1,165 @@
|
||||
# -*- coding: utf-8; mode: python -*-
|
||||
# pylint: disable=W0141,C0113,C0103,C0325
|
||||
u"""
|
||||
cdomain
|
||||
~~~~~~~
|
||||
|
||||
Replacement for the sphinx c-domain.
|
||||
|
||||
:copyright: Copyright (C) 2016 Markus Heiser
|
||||
:license: GPL Version 2, June 1991 see Linux/COPYING for details.
|
||||
|
||||
List of customizations:
|
||||
|
||||
* Moved the *duplicate C object description* warnings for function
|
||||
declarations in the nitpicky mode. See Sphinx documentation for
|
||||
the config values for ``nitpick`` and ``nitpick_ignore``.
|
||||
|
||||
* Add option 'name' to the "c:function:" directive. With option 'name' the
|
||||
ref-name of a function can be modified. E.g.::
|
||||
|
||||
.. c:function:: int ioctl( int fd, int request )
|
||||
:name: VIDIOC_LOG_STATUS
|
||||
|
||||
The func-name (e.g. ioctl) remains in the output but the ref-name changed
|
||||
from 'ioctl' to 'VIDIOC_LOG_STATUS'. The function is referenced by::
|
||||
|
||||
* :c:func:`VIDIOC_LOG_STATUS` or
|
||||
* :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3)
|
||||
|
||||
* Handle signatures of function-like macros well. Don't try to deduce
|
||||
arguments types of function-like macros.
|
||||
|
||||
"""
|
||||
|
||||
from docutils import nodes
|
||||
from docutils.parsers.rst import directives
|
||||
|
||||
import sphinx
|
||||
from sphinx import addnodes
|
||||
from sphinx.domains.c import c_funcptr_sig_re, c_sig_re
|
||||
from sphinx.domains.c import CObject as Base_CObject
|
||||
from sphinx.domains.c import CDomain as Base_CDomain
|
||||
|
||||
__version__ = '1.0'
|
||||
|
||||
# Get Sphinx version
|
||||
major, minor, patch = sphinx.version_info[:3]
|
||||
|
||||
def setup(app):
|
||||
|
||||
app.override_domain(CDomain)
|
||||
|
||||
return dict(
|
||||
version = __version__,
|
||||
parallel_read_safe = True,
|
||||
parallel_write_safe = True
|
||||
)
|
||||
|
||||
class CObject(Base_CObject):
|
||||
|
||||
"""
|
||||
Description of a C language object.
|
||||
"""
|
||||
option_spec = {
|
||||
"name" : directives.unchanged
|
||||
}
|
||||
|
||||
def handle_func_like_macro(self, sig, signode):
|
||||
u"""Handles signatures of function-like macros.
|
||||
|
||||
If the objtype is 'function' and the the signature ``sig`` is a
|
||||
function-like macro, the name of the macro is returned. Otherwise
|
||||
``False`` is returned. """
|
||||
|
||||
if not self.objtype == 'function':
|
||||
return False
|
||||
|
||||
m = c_funcptr_sig_re.match(sig)
|
||||
if m is None:
|
||||
m = c_sig_re.match(sig)
|
||||
if m is None:
|
||||
raise ValueError('no match')
|
||||
|
||||
rettype, fullname, arglist, _const = m.groups()
|
||||
arglist = arglist.strip()
|
||||
if rettype or not arglist:
|
||||
return False
|
||||
|
||||
arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup
|
||||
arglist = [a.strip() for a in arglist.split(",")]
|
||||
|
||||
# has the first argument a type?
|
||||
if len(arglist[0].split(" ")) > 1:
|
||||
return False
|
||||
|
||||
# This is a function-like macro, it's arguments are typeless!
|
||||
signode += addnodes.desc_name(fullname, fullname)
|
||||
paramlist = addnodes.desc_parameterlist()
|
||||
signode += paramlist
|
||||
|
||||
for argname in arglist:
|
||||
param = addnodes.desc_parameter('', '', noemph=True)
|
||||
# separate by non-breaking space in the output
|
||||
param += nodes.emphasis(argname, argname)
|
||||
paramlist += param
|
||||
|
||||
return fullname
|
||||
|
||||
def handle_signature(self, sig, signode):
|
||||
"""Transform a C signature into RST nodes."""
|
||||
|
||||
fullname = self.handle_func_like_macro(sig, signode)
|
||||
if not fullname:
|
||||
fullname = super(CObject, self).handle_signature(sig, signode)
|
||||
|
||||
if "name" in self.options:
|
||||
if self.objtype == 'function':
|
||||
fullname = self.options["name"]
|
||||
else:
|
||||
# FIXME: handle :name: value of other declaration types?
|
||||
pass
|
||||
return fullname
|
||||
|
||||
def add_target_and_index(self, name, sig, signode):
|
||||
# for C API items we add a prefix since names are usually not qualified
|
||||
# by a module name and so easily clash with e.g. section titles
|
||||
targetname = 'c.' + name
|
||||
if targetname not in self.state.document.ids:
|
||||
signode['names'].append(targetname)
|
||||
signode['ids'].append(targetname)
|
||||
signode['first'] = (not self.names)
|
||||
self.state.document.note_explicit_target(signode)
|
||||
inv = self.env.domaindata['c']['objects']
|
||||
if (name in inv and self.env.config.nitpicky):
|
||||
if self.objtype == 'function':
|
||||
if ('c:func', name) not in self.env.config.nitpick_ignore:
|
||||
self.state_machine.reporter.warning(
|
||||
'duplicate C object description of %s, ' % name +
|
||||
'other instance in ' + self.env.doc2path(inv[name][0]),
|
||||
line=self.lineno)
|
||||
inv[name] = (self.env.docname, self.objtype)
|
||||
|
||||
indextext = self.get_index_text(name)
|
||||
if indextext:
|
||||
if major == 1 and minor < 4:
|
||||
# indexnode's tuple changed in 1.4
|
||||
# https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c
|
||||
self.indexnode['entries'].append(
|
||||
('single', indextext, targetname, ''))
|
||||
else:
|
||||
self.indexnode['entries'].append(
|
||||
('single', indextext, targetname, '', None))
|
||||
|
||||
class CDomain(Base_CDomain):
|
||||
|
||||
"""C language domain."""
|
||||
name = 'c'
|
||||
label = 'C'
|
||||
directives = {
|
||||
'function': CObject,
|
||||
'member': CObject,
|
||||
'macro': CObject,
|
||||
'type': CObject,
|
||||
'var': CObject,
|
||||
}
|
||||
190
Documentation/sphinx/kernel_include.py
Executable file
190
Documentation/sphinx/kernel_include.py
Executable file
@ -0,0 +1,190 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8; mode: python -*-
|
||||
# pylint: disable=R0903, C0330, R0914, R0912, E0401
|
||||
|
||||
u"""
|
||||
kernel-include
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
Implementation of the ``kernel-include`` reST-directive.
|
||||
|
||||
:copyright: Copyright (C) 2016 Markus Heiser
|
||||
:license: GPL Version 2, June 1991 see linux/COPYING for details.
|
||||
|
||||
The ``kernel-include`` reST-directive is a replacement for the ``include``
|
||||
directive. The ``kernel-include`` directive expand environment variables in
|
||||
the path name and allows to include files from arbitrary locations.
|
||||
|
||||
.. hint::
|
||||
|
||||
Including files from arbitrary locations (e.g. from ``/etc``) is a
|
||||
security risk for builders. This is why the ``include`` directive from
|
||||
docutils *prohibit* pathnames pointing to locations *above* the filesystem
|
||||
tree where the reST document with the include directive is placed.
|
||||
|
||||
Substrings of the form $name or ${name} are replaced by the value of
|
||||
environment variable name. Malformed variable names and references to
|
||||
non-existing variables are left unchanged.
|
||||
"""
|
||||
|
||||
# ==============================================================================
|
||||
# imports
|
||||
# ==============================================================================
|
||||
|
||||
import os.path
|
||||
|
||||
from docutils import io, nodes, statemachine
|
||||
from docutils.utils.error_reporting import SafeString, ErrorString
|
||||
from docutils.parsers.rst import directives
|
||||
from docutils.parsers.rst.directives.body import CodeBlock, NumberLines
|
||||
from docutils.parsers.rst.directives.misc import Include
|
||||
|
||||
__version__ = '1.0'
|
||||
|
||||
# ==============================================================================
|
||||
def setup(app):
|
||||
# ==============================================================================
|
||||
|
||||
app.add_directive("kernel-include", KernelInclude)
|
||||
return dict(
|
||||
version = __version__,
|
||||
parallel_read_safe = True,
|
||||
parallel_write_safe = True
|
||||
)
|
||||
|
||||
# ==============================================================================
|
||||
class KernelInclude(Include):
|
||||
# ==============================================================================
|
||||
|
||||
u"""KernelInclude (``kernel-include``) directive"""
|
||||
|
||||
def run(self):
|
||||
path = os.path.realpath(
|
||||
os.path.expandvars(self.arguments[0]))
|
||||
|
||||
# to get a bit security back, prohibit /etc:
|
||||
if path.startswith(os.sep + "etc"):
|
||||
raise self.severe(
|
||||
'Problems with "%s" directive, prohibited path: %s'
|
||||
% (self.name, path))
|
||||
|
||||
self.arguments[0] = path
|
||||
|
||||
#return super(KernelInclude, self).run() # won't work, see HINTs in _run()
|
||||
return self._run()
|
||||
|
||||
def _run(self):
|
||||
"""Include a file as part of the content of this reST file."""
|
||||
|
||||
# HINT: I had to copy&paste the whole Include.run method. I'am not happy
|
||||
# with this, but due to security reasons, the Include.run method does
|
||||
# not allow absolute or relative pathnames pointing to locations *above*
|
||||
# the filesystem tree where the reST document is placed.
|
||||
|
||||
if not self.state.document.settings.file_insertion_enabled:
|
||||
raise self.warning('"%s" directive disabled.' % self.name)
|
||||
source = self.state_machine.input_lines.source(
|
||||
self.lineno - self.state_machine.input_offset - 1)
|
||||
source_dir = os.path.dirname(os.path.abspath(source))
|
||||
path = directives.path(self.arguments[0])
|
||||
if path.startswith('<') and path.endswith('>'):
|
||||
path = os.path.join(self.standard_include_path, path[1:-1])
|
||||
path = os.path.normpath(os.path.join(source_dir, path))
|
||||
|
||||
# HINT: this is the only line I had to change / commented out:
|
||||
#path = utils.relative_path(None, path)
|
||||
|
||||
path = nodes.reprunicode(path)
|
||||
encoding = self.options.get(
|
||||
'encoding', self.state.document.settings.input_encoding)
|
||||
e_handler=self.state.document.settings.input_encoding_error_handler
|
||||
tab_width = self.options.get(
|
||||
'tab-width', self.state.document.settings.tab_width)
|
||||
try:
|
||||
self.state.document.settings.record_dependencies.add(path)
|
||||
include_file = io.FileInput(source_path=path,
|
||||
encoding=encoding,
|
||||
error_handler=e_handler)
|
||||
except UnicodeEncodeError as error:
|
||||
raise self.severe('Problems with "%s" directive path:\n'
|
||||
'Cannot encode input file path "%s" '
|
||||
'(wrong locale?).' %
|
||||
(self.name, SafeString(path)))
|
||||
except IOError as error:
|
||||
raise self.severe('Problems with "%s" directive path:\n%s.' %
|
||||
(self.name, ErrorString(error)))
|
||||
startline = self.options.get('start-line', None)
|
||||
endline = self.options.get('end-line', None)
|
||||
try:
|
||||
if startline or (endline is not None):
|
||||
lines = include_file.readlines()
|
||||
rawtext = ''.join(lines[startline:endline])
|
||||
else:
|
||||
rawtext = include_file.read()
|
||||
except UnicodeError as error:
|
||||
raise self.severe('Problem with "%s" directive:\n%s' %
|
||||
(self.name, ErrorString(error)))
|
||||
# start-after/end-before: no restrictions on newlines in match-text,
|
||||
# and no restrictions on matching inside lines vs. line boundaries
|
||||
after_text = self.options.get('start-after', None)
|
||||
if after_text:
|
||||
# skip content in rawtext before *and incl.* a matching text
|
||||
after_index = rawtext.find(after_text)
|
||||
if after_index < 0:
|
||||
raise self.severe('Problem with "start-after" option of "%s" '
|
||||
'directive:\nText not found.' % self.name)
|
||||
rawtext = rawtext[after_index + len(after_text):]
|
||||
before_text = self.options.get('end-before', None)
|
||||
if before_text:
|
||||
# skip content in rawtext after *and incl.* a matching text
|
||||
before_index = rawtext.find(before_text)
|
||||
if before_index < 0:
|
||||
raise self.severe('Problem with "end-before" option of "%s" '
|
||||
'directive:\nText not found.' % self.name)
|
||||
rawtext = rawtext[:before_index]
|
||||
|
||||
include_lines = statemachine.string2lines(rawtext, tab_width,
|
||||
convert_whitespace=True)
|
||||
if 'literal' in self.options:
|
||||
# Convert tabs to spaces, if `tab_width` is positive.
|
||||
if tab_width >= 0:
|
||||
text = rawtext.expandtabs(tab_width)
|
||||
else:
|
||||
text = rawtext
|
||||
literal_block = nodes.literal_block(rawtext, source=path,
|
||||
classes=self.options.get('class', []))
|
||||
literal_block.line = 1
|
||||
self.add_name(literal_block)
|
||||
if 'number-lines' in self.options:
|
||||
try:
|
||||
startline = int(self.options['number-lines'] or 1)
|
||||
except ValueError:
|
||||
raise self.error(':number-lines: with non-integer '
|
||||
'start value')
|
||||
endline = startline + len(include_lines)
|
||||
if text.endswith('\n'):
|
||||
text = text[:-1]
|
||||
tokens = NumberLines([([], text)], startline, endline)
|
||||
for classes, value in tokens:
|
||||
if classes:
|
||||
literal_block += nodes.inline(value, value,
|
||||
classes=classes)
|
||||
else:
|
||||
literal_block += nodes.Text(value, value)
|
||||
else:
|
||||
literal_block += nodes.Text(text, text)
|
||||
return [literal_block]
|
||||
if 'code' in self.options:
|
||||
self.options['source'] = path
|
||||
codeblock = CodeBlock(self.name,
|
||||
[self.options.pop('code')], # arguments
|
||||
self.options,
|
||||
include_lines, # content
|
||||
self.lineno,
|
||||
self.content_offset,
|
||||
self.block_text,
|
||||
self.state,
|
||||
self.state_machine)
|
||||
return codeblock.run()
|
||||
self.state_machine.insert_input(include_lines, path)
|
||||
return []
|
||||
146
Documentation/sphinx/kerneldoc.py
Normal file
146
Documentation/sphinx/kerneldoc.py
Normal file
@ -0,0 +1,146 @@
|
||||
# coding=utf-8
|
||||
#
|
||||
# Copyright © 2016 Intel Corporation
|
||||
#
|
||||
# Permission is hereby granted, free of charge, to any person obtaining a
|
||||
# copy of this software and associated documentation files (the "Software"),
|
||||
# to deal in the Software without restriction, including without limitation
|
||||
# the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||
# and/or sell copies of the Software, and to permit persons to whom the
|
||||
# Software is furnished to do so, subject to the following conditions:
|
||||
#
|
||||
# The above copyright notice and this permission notice (including the next
|
||||
# paragraph) shall be included in all copies or substantial portions of the
|
||||
# Software.
|
||||
#
|
||||
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
|
||||
# IN THE SOFTWARE.
|
||||
#
|
||||
# Authors:
|
||||
# Jani Nikula <jani.nikula@intel.com>
|
||||
#
|
||||
# Please make sure this works on both python2 and python3.
|
||||
#
|
||||
|
||||
import codecs
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import re
|
||||
import glob
|
||||
|
||||
from docutils import nodes, statemachine
|
||||
from docutils.statemachine import ViewList
|
||||
from docutils.parsers.rst import directives, Directive
|
||||
from sphinx.ext.autodoc import AutodocReporter
|
||||
|
||||
__version__ = '1.0'
|
||||
|
||||
class KernelDocDirective(Directive):
|
||||
"""Extract kernel-doc comments from the specified file"""
|
||||
required_argument = 1
|
||||
optional_arguments = 4
|
||||
option_spec = {
|
||||
'doc': directives.unchanged_required,
|
||||
'functions': directives.unchanged_required,
|
||||
'export': directives.unchanged,
|
||||
'internal': directives.unchanged,
|
||||
}
|
||||
has_content = False
|
||||
|
||||
def run(self):
|
||||
env = self.state.document.settings.env
|
||||
cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno']
|
||||
|
||||
filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
|
||||
export_file_patterns = []
|
||||
|
||||
# Tell sphinx of the dependency
|
||||
env.note_dependency(os.path.abspath(filename))
|
||||
|
||||
tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)
|
||||
|
||||
# FIXME: make this nicer and more robust against errors
|
||||
if 'export' in self.options:
|
||||
cmd += ['-export']
|
||||
export_file_patterns = str(self.options.get('export')).split()
|
||||
elif 'internal' in self.options:
|
||||
cmd += ['-internal']
|
||||
export_file_patterns = str(self.options.get('internal')).split()
|
||||
elif 'doc' in self.options:
|
||||
cmd += ['-function', str(self.options.get('doc'))]
|
||||
elif 'functions' in self.options:
|
||||
for f in str(self.options.get('functions')).split():
|
||||
cmd += ['-function', f]
|
||||
|
||||
for pattern in export_file_patterns:
|
||||
for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
|
||||
env.note_dependency(os.path.abspath(f))
|
||||
cmd += ['-export-file', f]
|
||||
|
||||
cmd += [filename]
|
||||
|
||||
try:
|
||||
env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd)))
|
||||
|
||||
p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
|
||||
out, err = p.communicate()
|
||||
|
||||
out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
|
||||
|
||||
if p.returncode != 0:
|
||||
sys.stderr.write(err)
|
||||
|
||||
env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))
|
||||
return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
|
||||
elif env.config.kerneldoc_verbosity > 0:
|
||||
sys.stderr.write(err)
|
||||
|
||||
lines = statemachine.string2lines(out, tab_width, convert_whitespace=True)
|
||||
result = ViewList()
|
||||
|
||||
lineoffset = 0;
|
||||
line_regex = re.compile("^#define LINENO ([0-9]+)$")
|
||||
for line in lines:
|
||||
match = line_regex.search(line)
|
||||
if match:
|
||||
# sphinx counts lines from 0
|
||||
lineoffset = int(match.group(1)) - 1
|
||||
# we must eat our comments since the upset the markup
|
||||
else:
|
||||
result.append(line, filename, lineoffset)
|
||||
lineoffset += 1
|
||||
|
||||
node = nodes.section()
|
||||
buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
|
||||
self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
|
||||
self.state.memo.title_styles, self.state.memo.section_level = [], 0
|
||||
try:
|
||||
self.state.nested_parse(result, 0, node, match_titles=1)
|
||||
finally:
|
||||
self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
|
||||
|
||||
return node.children
|
||||
|
||||
except Exception as e: # pylint: disable=W0703
|
||||
env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
|
||||
(" ".join(cmd), str(e)))
|
||||
return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
|
||||
|
||||
def setup(app):
|
||||
app.add_config_value('kerneldoc_bin', None, 'env')
|
||||
app.add_config_value('kerneldoc_srctree', None, 'env')
|
||||
app.add_config_value('kerneldoc_verbosity', 1, 'env')
|
||||
|
||||
app.add_directive('kernel-doc', KernelDocDirective)
|
||||
|
||||
return dict(
|
||||
version = __version__,
|
||||
parallel_read_safe = True,
|
||||
parallel_write_safe = True
|
||||
)
|
||||
551
Documentation/sphinx/kfigure.py
Normal file
551
Documentation/sphinx/kfigure.py
Normal file
@ -0,0 +1,551 @@
|
||||
# -*- coding: utf-8; mode: python -*-
|
||||
# pylint: disable=C0103, R0903, R0912, R0915
|
||||
u"""
|
||||
scalable figure and image handling
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Sphinx extension which implements scalable image handling.
|
||||
|
||||
:copyright: Copyright (C) 2016 Markus Heiser
|
||||
:license: GPL Version 2, June 1991 see Linux/COPYING for details.
|
||||
|
||||
The build for image formats depend on image's source format and output's
|
||||
destination format. This extension implement methods to simplify image
|
||||
handling from the author's POV. Directives like ``kernel-figure`` implement
|
||||
methods *to* always get the best output-format even if some tools are not
|
||||
installed. For more details take a look at ``convert_image(...)`` which is
|
||||
the core of all conversions.
|
||||
|
||||
* ``.. kernel-image``: for image handling / a ``.. image::`` replacement
|
||||
|
||||
* ``.. kernel-figure``: for figure handling / a ``.. figure::`` replacement
|
||||
|
||||
* ``.. kernel-render``: for render markup / a concept to embed *render*
|
||||
markups (or languages). Supported markups (see ``RENDER_MARKUP_EXT``)
|
||||
|
||||
- ``DOT``: render embedded Graphviz's **DOC**
|
||||
- ``SVG``: render embedded Scalable Vector Graphics (**SVG**)
|
||||
- ... *developable*
|
||||
|
||||
Used tools:
|
||||
|
||||
* ``dot(1)``: Graphviz (http://www.graphviz.org). If Graphviz is not
|
||||
available, the DOT language is inserted as literal-block.
|
||||
|
||||
* SVG to PDF: To generate PDF, you need at least one of this tools:
|
||||
|
||||
- ``convert(1)``: ImageMagick (https://www.imagemagick.org)
|
||||
|
||||
List of customizations:
|
||||
|
||||
* generate PDF from SVG / used by PDF (LaTeX) builder
|
||||
|
||||
* generate SVG (html-builder) and PDF (latex-builder) from DOT files.
|
||||
DOT: see http://www.graphviz.org/content/dot-language
|
||||
|
||||
"""
|
||||
|
||||
import os
|
||||
from os import path
|
||||
import subprocess
|
||||
from hashlib import sha1
|
||||
import sys
|
||||
|
||||
from docutils import nodes
|
||||
from docutils.statemachine import ViewList
|
||||
from docutils.parsers.rst import directives
|
||||
from docutils.parsers.rst.directives import images
|
||||
import sphinx
|
||||
|
||||
from sphinx.util.nodes import clean_astext
|
||||
from six import iteritems
|
||||
|
||||
PY3 = sys.version_info[0] == 3
|
||||
|
||||
if PY3:
|
||||
_unicode = str
|
||||
else:
|
||||
_unicode = unicode
|
||||
|
||||
# Get Sphinx version
|
||||
major, minor, patch = sphinx.version_info[:3]
|
||||
if major == 1 and minor > 3:
|
||||
# patches.Figure only landed in Sphinx 1.4
|
||||
from sphinx.directives.patches import Figure # pylint: disable=C0413
|
||||
else:
|
||||
Figure = images.Figure
|
||||
|
||||
__version__ = '1.0.0'
|
||||
|
||||
# simple helper
|
||||
# -------------
|
||||
|
||||
def which(cmd):
|
||||
"""Searches the ``cmd`` in the ``PATH`` environment.
|
||||
|
||||
This *which* searches the PATH for executable ``cmd`` . First match is
|
||||
returned, if nothing is found, ``None` is returned.
|
||||
"""
|
||||
envpath = os.environ.get('PATH', None) or os.defpath
|
||||
for folder in envpath.split(os.pathsep):
|
||||
fname = folder + os.sep + cmd
|
||||
if path.isfile(fname):
|
||||
return fname
|
||||
|
||||
def mkdir(folder, mode=0o775):
|
||||
if not path.isdir(folder):
|
||||
os.makedirs(folder, mode)
|
||||
|
||||
def file2literal(fname):
|
||||
with open(fname, "r") as src:
|
||||
data = src.read()
|
||||
node = nodes.literal_block(data, data)
|
||||
return node
|
||||
|
||||
def isNewer(path1, path2):
|
||||
"""Returns True if ``path1`` is newer than ``path2``
|
||||
|
||||
If ``path1`` exists and is newer than ``path2`` the function returns
|
||||
``True`` is returned otherwise ``False``
|
||||
"""
|
||||
return (path.exists(path1)
|
||||
and os.stat(path1).st_ctime > os.stat(path2).st_ctime)
|
||||
|
||||
def pass_handle(self, node): # pylint: disable=W0613
|
||||
pass
|
||||
|
||||
# setup conversion tools and sphinx extension
|
||||
# -------------------------------------------
|
||||
|
||||
# Graphviz's dot(1) support
|
||||
dot_cmd = None
|
||||
|
||||
# ImageMagick' convert(1) support
|
||||
convert_cmd = None
|
||||
|
||||
|
||||
def setup(app):
|
||||
# check toolchain first
|
||||
app.connect('builder-inited', setupTools)
|
||||
|
||||
# image handling
|
||||
app.add_directive("kernel-image", KernelImage)
|
||||
app.add_node(kernel_image,
|
||||
html = (visit_kernel_image, pass_handle),
|
||||
latex = (visit_kernel_image, pass_handle),
|
||||
texinfo = (visit_kernel_image, pass_handle),
|
||||
text = (visit_kernel_image, pass_handle),
|
||||
man = (visit_kernel_image, pass_handle), )
|
||||
|
||||
# figure handling
|
||||
app.add_directive("kernel-figure", KernelFigure)
|
||||
app.add_node(kernel_figure,
|
||||
html = (visit_kernel_figure, pass_handle),
|
||||
latex = (visit_kernel_figure, pass_handle),
|
||||
texinfo = (visit_kernel_figure, pass_handle),
|
||||
text = (visit_kernel_figure, pass_handle),
|
||||
man = (visit_kernel_figure, pass_handle), )
|
||||
|
||||
# render handling
|
||||
app.add_directive('kernel-render', KernelRender)
|
||||
app.add_node(kernel_render,
|
||||
html = (visit_kernel_render, pass_handle),
|
||||
latex = (visit_kernel_render, pass_handle),
|
||||
texinfo = (visit_kernel_render, pass_handle),
|
||||
text = (visit_kernel_render, pass_handle),
|
||||
man = (visit_kernel_render, pass_handle), )
|
||||
|
||||
app.connect('doctree-read', add_kernel_figure_to_std_domain)
|
||||
|
||||
return dict(
|
||||
version = __version__,
|
||||
parallel_read_safe = True,
|
||||
parallel_write_safe = True
|
||||
)
|
||||
|
||||
|
||||
def setupTools(app):
|
||||
u"""
|
||||
Check available build tools and log some *verbose* messages.
|
||||
|
||||
This function is called once, when the builder is initiated.
|
||||
"""
|
||||
global dot_cmd, convert_cmd # pylint: disable=W0603
|
||||
app.verbose("kfigure: check installed tools ...")
|
||||
|
||||
dot_cmd = which('dot')
|
||||
convert_cmd = which('convert')
|
||||
|
||||
if dot_cmd:
|
||||
app.verbose("use dot(1) from: " + dot_cmd)
|
||||
else:
|
||||
app.warn("dot(1) not found, for better output quality install "
|
||||
"graphviz from http://www.graphviz.org")
|
||||
if convert_cmd:
|
||||
app.verbose("use convert(1) from: " + convert_cmd)
|
||||
else:
|
||||
app.warn(
|
||||
"convert(1) not found, for SVG to PDF conversion install "
|
||||
"ImageMagick (https://www.imagemagick.org)")
|
||||
|
||||
|
||||
# integrate conversion tools
|
||||
# --------------------------
|
||||
|
||||
RENDER_MARKUP_EXT = {
|
||||
# The '.ext' must be handled by convert_image(..) function's *in_ext* input.
|
||||
# <name> : <.ext>
|
||||
'DOT' : '.dot',
|
||||
'SVG' : '.svg'
|
||||
}
|
||||
|
||||
def convert_image(img_node, translator, src_fname=None):
|
||||
"""Convert a image node for the builder.
|
||||
|
||||
Different builder prefer different image formats, e.g. *latex* builder
|
||||
prefer PDF while *html* builder prefer SVG format for images.
|
||||
|
||||
This function handles output image formats in dependence of source the
|
||||
format (of the image) and the translator's output format.
|
||||
"""
|
||||
app = translator.builder.app
|
||||
|
||||
fname, in_ext = path.splitext(path.basename(img_node['uri']))
|
||||
if src_fname is None:
|
||||
src_fname = path.join(translator.builder.srcdir, img_node['uri'])
|
||||
if not path.exists(src_fname):
|
||||
src_fname = path.join(translator.builder.outdir, img_node['uri'])
|
||||
|
||||
dst_fname = None
|
||||
|
||||
# in kernel builds, use 'make SPHINXOPTS=-v' to see verbose messages
|
||||
|
||||
app.verbose('assert best format for: ' + img_node['uri'])
|
||||
|
||||
if in_ext == '.dot':
|
||||
|
||||
if not dot_cmd:
|
||||
app.verbose("dot from graphviz not available / include DOT raw.")
|
||||
img_node.replace_self(file2literal(src_fname))
|
||||
|
||||
elif translator.builder.format == 'latex':
|
||||
dst_fname = path.join(translator.builder.outdir, fname + '.pdf')
|
||||
img_node['uri'] = fname + '.pdf'
|
||||
img_node['candidates'] = {'*': fname + '.pdf'}
|
||||
|
||||
|
||||
elif translator.builder.format == 'html':
|
||||
dst_fname = path.join(
|
||||
translator.builder.outdir,
|
||||
translator.builder.imagedir,
|
||||
fname + '.svg')
|
||||
img_node['uri'] = path.join(
|
||||
translator.builder.imgpath, fname + '.svg')
|
||||
img_node['candidates'] = {
|
||||
'*': path.join(translator.builder.imgpath, fname + '.svg')}
|
||||
|
||||
else:
|
||||
# all other builder formats will include DOT as raw
|
||||
img_node.replace_self(file2literal(src_fname))
|
||||
|
||||
elif in_ext == '.svg':
|
||||
|
||||
if translator.builder.format == 'latex':
|
||||
if convert_cmd is None:
|
||||
app.verbose("no SVG to PDF conversion available / include SVG raw.")
|
||||
img_node.replace_self(file2literal(src_fname))
|
||||
else:
|
||||
dst_fname = path.join(translator.builder.outdir, fname + '.pdf')
|
||||
img_node['uri'] = fname + '.pdf'
|
||||
img_node['candidates'] = {'*': fname + '.pdf'}
|
||||
|
||||
if dst_fname:
|
||||
# the builder needs not to copy one more time, so pop it if exists.
|
||||
translator.builder.images.pop(img_node['uri'], None)
|
||||
_name = dst_fname[len(translator.builder.outdir) + 1:]
|
||||
|
||||
if isNewer(dst_fname, src_fname):
|
||||
app.verbose("convert: {out}/%s already exists and is newer" % _name)
|
||||
|
||||
else:
|
||||
ok = False
|
||||
mkdir(path.dirname(dst_fname))
|
||||
|
||||
if in_ext == '.dot':
|
||||
app.verbose('convert DOT to: {out}/' + _name)
|
||||
ok = dot2format(app, src_fname, dst_fname)
|
||||
|
||||
elif in_ext == '.svg':
|
||||
app.verbose('convert SVG to: {out}/' + _name)
|
||||
ok = svg2pdf(app, src_fname, dst_fname)
|
||||
|
||||
if not ok:
|
||||
img_node.replace_self(file2literal(src_fname))
|
||||
|
||||
|
||||
def dot2format(app, dot_fname, out_fname):
|
||||
"""Converts DOT file to ``out_fname`` using ``dot(1)``.
|
||||
|
||||
* ``dot_fname`` pathname of the input DOT file, including extension ``.dot``
|
||||
* ``out_fname`` pathname of the output file, including format extension
|
||||
|
||||
The *format extension* depends on the ``dot`` command (see ``man dot``
|
||||
option ``-Txxx``). Normally you will use one of the following extensions:
|
||||
|
||||
- ``.ps`` for PostScript,
|
||||
- ``.svg`` or ``svgz`` for Structured Vector Graphics,
|
||||
- ``.fig`` for XFIG graphics and
|
||||
- ``.png`` or ``gif`` for common bitmap graphics.
|
||||
|
||||
"""
|
||||
out_format = path.splitext(out_fname)[1][1:]
|
||||
cmd = [dot_cmd, '-T%s' % out_format, dot_fname]
|
||||
exit_code = 42
|
||||
|
||||
with open(out_fname, "w") as out:
|
||||
exit_code = subprocess.call(cmd, stdout = out)
|
||||
if exit_code != 0:
|
||||
app.warn("Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
|
||||
return bool(exit_code == 0)
|
||||
|
||||
def svg2pdf(app, svg_fname, pdf_fname):
|
||||
"""Converts SVG to PDF with ``convert(1)`` command.
|
||||
|
||||
Uses ``convert(1)`` from ImageMagick (https://www.imagemagick.org) for
|
||||
conversion. Returns ``True`` on success and ``False`` if an error occurred.
|
||||
|
||||
* ``svg_fname`` pathname of the input SVG file with extension (``.svg``)
|
||||
* ``pdf_name`` pathname of the output PDF file with extension (``.pdf``)
|
||||
|
||||
"""
|
||||
cmd = [convert_cmd, svg_fname, pdf_fname]
|
||||
# use stdout and stderr from parent
|
||||
exit_code = subprocess.call(cmd)
|
||||
if exit_code != 0:
|
||||
app.warn("Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
|
||||
return bool(exit_code == 0)
|
||||
|
||||
|
||||
# image handling
|
||||
# ---------------------
|
||||
|
||||
def visit_kernel_image(self, node): # pylint: disable=W0613
|
||||
"""Visitor of the ``kernel_image`` Node.
|
||||
|
||||
Handles the ``image`` child-node with the ``convert_image(...)``.
|
||||
"""
|
||||
img_node = node[0]
|
||||
convert_image(img_node, self)
|
||||
|
||||
class kernel_image(nodes.image):
|
||||
"""Node for ``kernel-image`` directive."""
|
||||
pass
|
||||
|
||||
class KernelImage(images.Image):
|
||||
u"""KernelImage directive
|
||||
|
||||
Earns everything from ``.. image::`` directive, except *remote URI* and
|
||||
*glob* pattern. The KernelImage wraps a image node into a
|
||||
kernel_image node. See ``visit_kernel_image``.
|
||||
"""
|
||||
|
||||
def run(self):
|
||||
uri = self.arguments[0]
|
||||
if uri.endswith('.*') or uri.find('://') != -1:
|
||||
raise self.severe(
|
||||
'Error in "%s: %s": glob pattern and remote images are not allowed'
|
||||
% (self.name, uri))
|
||||
result = images.Image.run(self)
|
||||
if len(result) == 2 or isinstance(result[0], nodes.system_message):
|
||||
return result
|
||||
(image_node,) = result
|
||||
# wrap image node into a kernel_image node / see visitors
|
||||
node = kernel_image('', image_node)
|
||||
return [node]
|
||||
|
||||
# figure handling
|
||||
# ---------------------
|
||||
|
||||
def visit_kernel_figure(self, node): # pylint: disable=W0613
|
||||
"""Visitor of the ``kernel_figure`` Node.
|
||||
|
||||
Handles the ``image`` child-node with the ``convert_image(...)``.
|
||||
"""
|
||||
img_node = node[0][0]
|
||||
convert_image(img_node, self)
|
||||
|
||||
class kernel_figure(nodes.figure):
|
||||
"""Node for ``kernel-figure`` directive."""
|
||||
|
||||
class KernelFigure(Figure):
|
||||
u"""KernelImage directive
|
||||
|
||||
Earns everything from ``.. figure::`` directive, except *remote URI* and
|
||||
*glob* pattern. The KernelFigure wraps a figure node into a kernel_figure
|
||||
node. See ``visit_kernel_figure``.
|
||||
"""
|
||||
|
||||
def run(self):
|
||||
uri = self.arguments[0]
|
||||
if uri.endswith('.*') or uri.find('://') != -1:
|
||||
raise self.severe(
|
||||
'Error in "%s: %s":'
|
||||
' glob pattern and remote images are not allowed'
|
||||
% (self.name, uri))
|
||||
result = Figure.run(self)
|
||||
if len(result) == 2 or isinstance(result[0], nodes.system_message):
|
||||
return result
|
||||
(figure_node,) = result
|
||||
# wrap figure node into a kernel_figure node / see visitors
|
||||
node = kernel_figure('', figure_node)
|
||||
return [node]
|
||||
|
||||
|
||||
# render handling
|
||||
# ---------------------
|
||||
|
||||
def visit_kernel_render(self, node):
|
||||
"""Visitor of the ``kernel_render`` Node.
|
||||
|
||||
If rendering tools available, save the markup of the ``literal_block`` child
|
||||
node into a file and replace the ``literal_block`` node with a new created
|
||||
``image`` node, pointing to the saved markup file. Afterwards, handle the
|
||||
image child-node with the ``convert_image(...)``.
|
||||
"""
|
||||
app = self.builder.app
|
||||
srclang = node.get('srclang')
|
||||
|
||||
app.verbose('visit kernel-render node lang: "%s"' % (srclang))
|
||||
|
||||
tmp_ext = RENDER_MARKUP_EXT.get(srclang, None)
|
||||
if tmp_ext is None:
|
||||
app.warn('kernel-render: "%s" unknown / include raw.' % (srclang))
|
||||
return
|
||||
|
||||
if not dot_cmd and tmp_ext == '.dot':
|
||||
app.verbose("dot from graphviz not available / include raw.")
|
||||
return
|
||||
|
||||
literal_block = node[0]
|
||||
|
||||
code = literal_block.astext()
|
||||
hashobj = code.encode('utf-8') # str(node.attributes)
|
||||
fname = path.join('%s-%s' % (srclang, sha1(hashobj).hexdigest()))
|
||||
|
||||
tmp_fname = path.join(
|
||||
self.builder.outdir, self.builder.imagedir, fname + tmp_ext)
|
||||
|
||||
if not path.isfile(tmp_fname):
|
||||
mkdir(path.dirname(tmp_fname))
|
||||
with open(tmp_fname, "w") as out:
|
||||
out.write(code)
|
||||
|
||||
img_node = nodes.image(node.rawsource, **node.attributes)
|
||||
img_node['uri'] = path.join(self.builder.imgpath, fname + tmp_ext)
|
||||
img_node['candidates'] = {
|
||||
'*': path.join(self.builder.imgpath, fname + tmp_ext)}
|
||||
|
||||
literal_block.replace_self(img_node)
|
||||
convert_image(img_node, self, tmp_fname)
|
||||
|
||||
|
||||
class kernel_render(nodes.General, nodes.Inline, nodes.Element):
|
||||
"""Node for ``kernel-render`` directive."""
|
||||
pass
|
||||
|
||||
class KernelRender(Figure):
|
||||
u"""KernelRender directive
|
||||
|
||||
Render content by external tool. Has all the options known from the
|
||||
*figure* directive, plus option ``caption``. If ``caption`` has a
|
||||
value, a figure node with the *caption* is inserted. If not, a image node is
|
||||
inserted.
|
||||
|
||||
The KernelRender directive wraps the text of the directive into a
|
||||
literal_block node and wraps it into a kernel_render node. See
|
||||
``visit_kernel_render``.
|
||||
"""
|
||||
has_content = True
|
||||
required_arguments = 1
|
||||
optional_arguments = 0
|
||||
final_argument_whitespace = False
|
||||
|
||||
# earn options from 'figure'
|
||||
option_spec = Figure.option_spec.copy()
|
||||
option_spec['caption'] = directives.unchanged
|
||||
|
||||
def run(self):
|
||||
return [self.build_node()]
|
||||
|
||||
def build_node(self):
|
||||
|
||||
srclang = self.arguments[0].strip()
|
||||
if srclang not in RENDER_MARKUP_EXT.keys():
|
||||
return [self.state_machine.reporter.warning(
|
||||
'Unknown source language "%s", use one of: %s.' % (
|
||||
srclang, ",".join(RENDER_MARKUP_EXT.keys())),
|
||||
line=self.lineno)]
|
||||
|
||||
code = '\n'.join(self.content)
|
||||
if not code.strip():
|
||||
return [self.state_machine.reporter.warning(
|
||||
'Ignoring "%s" directive without content.' % (
|
||||
self.name),
|
||||
line=self.lineno)]
|
||||
|
||||
node = kernel_render()
|
||||
node['alt'] = self.options.get('alt','')
|
||||
node['srclang'] = srclang
|
||||
literal_node = nodes.literal_block(code, code)
|
||||
node += literal_node
|
||||
|
||||
caption = self.options.get('caption')
|
||||
if caption:
|
||||
# parse caption's content
|
||||
parsed = nodes.Element()
|
||||
self.state.nested_parse(
|
||||
ViewList([caption], source=''), self.content_offset, parsed)
|
||||
caption_node = nodes.caption(
|
||||
parsed[0].rawsource, '', *parsed[0].children)
|
||||
caption_node.source = parsed[0].source
|
||||
caption_node.line = parsed[0].line
|
||||
|
||||
figure_node = nodes.figure('', node)
|
||||
for k,v in self.options.items():
|
||||
figure_node[k] = v
|
||||
figure_node += caption_node
|
||||
|
||||
node = figure_node
|
||||
|
||||
return node
|
||||
|
||||
def add_kernel_figure_to_std_domain(app, doctree):
|
||||
"""Add kernel-figure anchors to 'std' domain.
|
||||
|
||||
The ``StandardDomain.process_doc(..)`` method does not know how to resolve
|
||||
the caption (label) of ``kernel-figure`` directive (it only knows about
|
||||
standard nodes, e.g. table, figure etc.). Without any additional handling
|
||||
this will result in a 'undefined label' for kernel-figures.
|
||||
|
||||
This handle adds labels of kernel-figure to the 'std' domain labels.
|
||||
"""
|
||||
|
||||
std = app.env.domains["std"]
|
||||
docname = app.env.docname
|
||||
labels = std.data["labels"]
|
||||
|
||||
for name, explicit in iteritems(doctree.nametypes):
|
||||
if not explicit:
|
||||
continue
|
||||
labelid = doctree.nameids[name]
|
||||
if labelid is None:
|
||||
continue
|
||||
node = doctree.ids[labelid]
|
||||
|
||||
if node.tagname == 'kernel_figure':
|
||||
for n in node.next_node():
|
||||
if n.tagname == 'caption':
|
||||
sectname = clean_astext(n)
|
||||
# add label to std domain
|
||||
labels[name] = docname, labelid, sectname
|
||||
break
|
||||
32
Documentation/sphinx/load_config.py
Normal file
32
Documentation/sphinx/load_config.py
Normal file
@ -0,0 +1,32 @@
|
||||
# -*- coding: utf-8; mode: python -*-
|
||||
# pylint: disable=R0903, C0330, R0914, R0912, E0401
|
||||
|
||||
import os
|
||||
import sys
|
||||
from sphinx.util.pycompat import execfile_
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
def loadConfig(namespace):
|
||||
# ------------------------------------------------------------------------------
|
||||
|
||||
u"""Load an additional configuration file into *namespace*.
|
||||
|
||||
The name of the configuration file is taken from the environment
|
||||
``SPHINX_CONF``. The external configuration file extends (or overwrites) the
|
||||
configuration values from the origin ``conf.py``. With this you are able to
|
||||
maintain *build themes*. """
|
||||
|
||||
config_file = os.environ.get("SPHINX_CONF", None)
|
||||
if (config_file is not None
|
||||
and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ):
|
||||
config_file = os.path.abspath(config_file)
|
||||
|
||||
if os.path.isfile(config_file):
|
||||
sys.stdout.write("load additional sphinx-config: %s\n" % config_file)
|
||||
config = namespace.copy()
|
||||
config['__file__'] = config_file
|
||||
execfile_(config_file, config)
|
||||
del config['__file__']
|
||||
namespace.update(config)
|
||||
else:
|
||||
sys.stderr.write("WARNING: additional sphinx-config not found: %s\n" % config_file)
|
||||
401
Documentation/sphinx/parse-headers.pl
Executable file
401
Documentation/sphinx/parse-headers.pl
Executable file
@ -0,0 +1,401 @@
|
||||
#!/usr/bin/perl
|
||||
use strict;
|
||||
use Text::Tabs;
|
||||
use Getopt::Long;
|
||||
use Pod::Usage;
|
||||
|
||||
my $debug;
|
||||
my $help;
|
||||
my $man;
|
||||
|
||||
GetOptions(
|
||||
"debug" => \$debug,
|
||||
'usage|?' => \$help,
|
||||
'help' => \$man
|
||||
) or pod2usage(2);
|
||||
|
||||
pod2usage(1) if $help;
|
||||
pod2usage(-exitstatus => 0, -verbose => 2) if $man;
|
||||
pod2usage(2) if (scalar @ARGV < 2 || scalar @ARGV > 3);
|
||||
|
||||
my ($file_in, $file_out, $file_exceptions) = @ARGV;
|
||||
|
||||
my $data;
|
||||
my %ioctls;
|
||||
my %defines;
|
||||
my %typedefs;
|
||||
my %enums;
|
||||
my %enum_symbols;
|
||||
my %structs;
|
||||
|
||||
require Data::Dumper if ($debug);
|
||||
|
||||
#
|
||||
# read the file and get identifiers
|
||||
#
|
||||
|
||||
my $is_enum = 0;
|
||||
my $is_comment = 0;
|
||||
open IN, $file_in or die "Can't open $file_in";
|
||||
while (<IN>) {
|
||||
$data .= $_;
|
||||
|
||||
my $ln = $_;
|
||||
if (!$is_comment) {
|
||||
$ln =~ s,/\*.*(\*/),,g;
|
||||
|
||||
$is_comment = 1 if ($ln =~ s,/\*.*,,);
|
||||
} else {
|
||||
if ($ln =~ s,^(.*\*/),,) {
|
||||
$is_comment = 0;
|
||||
} else {
|
||||
next;
|
||||
}
|
||||
}
|
||||
|
||||
if ($is_enum && $ln =~ m/^\s*([_\w][\w\d_]+)\s*[\,=]?/) {
|
||||
my $s = $1;
|
||||
my $n = $1;
|
||||
$n =~ tr/A-Z/a-z/;
|
||||
$n =~ tr/_/-/;
|
||||
|
||||
$enum_symbols{$s} = "\\ :ref:`$s <$n>`\\ ";
|
||||
|
||||
$is_enum = 0 if ($is_enum && m/\}/);
|
||||
next;
|
||||
}
|
||||
$is_enum = 0 if ($is_enum && m/\}/);
|
||||
|
||||
if ($ln =~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+_IO/) {
|
||||
my $s = $1;
|
||||
my $n = $1;
|
||||
$n =~ tr/A-Z/a-z/;
|
||||
|
||||
$ioctls{$s} = "\\ :ref:`$s <$n>`\\ ";
|
||||
next;
|
||||
}
|
||||
|
||||
if ($ln =~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+/) {
|
||||
my $s = $1;
|
||||
my $n = $1;
|
||||
$n =~ tr/A-Z/a-z/;
|
||||
$n =~ tr/_/-/;
|
||||
|
||||
$defines{$s} = "\\ :ref:`$s <$n>`\\ ";
|
||||
next;
|
||||
}
|
||||
|
||||
if ($ln =~ m/^\s*typedef\s+([_\w][\w\d_]+)\s+(.*)\s+([_\w][\w\d_]+);/) {
|
||||
my $s = $2;
|
||||
my $n = $3;
|
||||
|
||||
$typedefs{$n} = "\\ :c:type:`$n <$s>`\\ ";
|
||||
next;
|
||||
}
|
||||
if ($ln =~ m/^\s*enum\s+([_\w][\w\d_]+)\s+\{/
|
||||
|| $ln =~ m/^\s*enum\s+([_\w][\w\d_]+)$/
|
||||
|| $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)\s+\{/
|
||||
|| $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)$/) {
|
||||
my $s = $1;
|
||||
|
||||
$enums{$s} = "enum :c:type:`$s`\\ ";
|
||||
|
||||
$is_enum = $1;
|
||||
next;
|
||||
}
|
||||
if ($ln =~ m/^\s*struct\s+([_\w][\w\d_]+)\s+\{/
|
||||
|| $ln =~ m/^\s*struct\s+([[_\w][\w\d_]+)$/
|
||||
|| $ln =~ m/^\s*typedef\s*struct\s+([_\w][\w\d_]+)\s+\{/
|
||||
|| $ln =~ m/^\s*typedef\s*struct\s+([[_\w][\w\d_]+)$/
|
||||
) {
|
||||
my $s = $1;
|
||||
|
||||
$structs{$s} = "struct :c:type:`$s`\\ ";
|
||||
next;
|
||||
}
|
||||
}
|
||||
close IN;
|
||||
|
||||
#
|
||||
# Handle multi-line typedefs
|
||||
#
|
||||
|
||||
my @matches = ($data =~ m/typedef\s+struct\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g,
|
||||
$data =~ m/typedef\s+enum\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g,);
|
||||
foreach my $m (@matches) {
|
||||
my $s = $m;
|
||||
|
||||
$typedefs{$s} = "\\ :c:type:`$s`\\ ";
|
||||
next;
|
||||
}
|
||||
|
||||
#
|
||||
# Handle exceptions, if any
|
||||
#
|
||||
|
||||
my %def_reftype = (
|
||||
"ioctl" => ":ref",
|
||||
"define" => ":ref",
|
||||
"symbol" => ":ref",
|
||||
"typedef" => ":c:type",
|
||||
"enum" => ":c:type",
|
||||
"struct" => ":c:type",
|
||||
);
|
||||
|
||||
if ($file_exceptions) {
|
||||
open IN, $file_exceptions or die "Can't read $file_exceptions";
|
||||
while (<IN>) {
|
||||
next if (m/^\s*$/ || m/^\s*#/);
|
||||
|
||||
# Parsers to ignore a symbol
|
||||
|
||||
if (m/^ignore\s+ioctl\s+(\S+)/) {
|
||||
delete $ioctls{$1} if (exists($ioctls{$1}));
|
||||
next;
|
||||
}
|
||||
if (m/^ignore\s+define\s+(\S+)/) {
|
||||
delete $defines{$1} if (exists($defines{$1}));
|
||||
next;
|
||||
}
|
||||
if (m/^ignore\s+typedef\s+(\S+)/) {
|
||||
delete $typedefs{$1} if (exists($typedefs{$1}));
|
||||
next;
|
||||
}
|
||||
if (m/^ignore\s+enum\s+(\S+)/) {
|
||||
delete $enums{$1} if (exists($enums{$1}));
|
||||
next;
|
||||
}
|
||||
if (m/^ignore\s+struct\s+(\S+)/) {
|
||||
delete $structs{$1} if (exists($structs{$1}));
|
||||
next;
|
||||
}
|
||||
if (m/^ignore\s+symbol\s+(\S+)/) {
|
||||
delete $enum_symbols{$1} if (exists($enum_symbols{$1}));
|
||||
next;
|
||||
}
|
||||
|
||||
# Parsers to replace a symbol
|
||||
my ($type, $old, $new, $reftype);
|
||||
|
||||
if (m/^replace\s+(\S+)\s+(\S+)\s+(\S+)/) {
|
||||
$type = $1;
|
||||
$old = $2;
|
||||
$new = $3;
|
||||
} else {
|
||||
die "Can't parse $file_exceptions: $_";
|
||||
}
|
||||
|
||||
if ($new =~ m/^\:c\:(data|func|macro|type)\:\`(.+)\`/) {
|
||||
$reftype = ":c:$1";
|
||||
$new = $2;
|
||||
} elsif ($new =~ m/\:ref\:\`(.+)\`/) {
|
||||
$reftype = ":ref";
|
||||
$new = $1;
|
||||
} else {
|
||||
$reftype = $def_reftype{$type};
|
||||
}
|
||||
$new = "$reftype:`$old <$new>`";
|
||||
|
||||
if ($type eq "ioctl") {
|
||||
$ioctls{$old} = $new if (exists($ioctls{$old}));
|
||||
next;
|
||||
}
|
||||
if ($type eq "define") {
|
||||
$defines{$old} = $new if (exists($defines{$old}));
|
||||
next;
|
||||
}
|
||||
if ($type eq "symbol") {
|
||||
$enum_symbols{$old} = $new if (exists($enum_symbols{$old}));
|
||||
next;
|
||||
}
|
||||
if ($type eq "typedef") {
|
||||
$typedefs{$old} = $new if (exists($typedefs{$old}));
|
||||
next;
|
||||
}
|
||||
if ($type eq "enum") {
|
||||
$enums{$old} = $new if (exists($enums{$old}));
|
||||
next;
|
||||
}
|
||||
if ($type eq "struct") {
|
||||
$structs{$old} = $new if (exists($structs{$old}));
|
||||
next;
|
||||
}
|
||||
|
||||
die "Can't parse $file_exceptions: $_";
|
||||
}
|
||||
}
|
||||
|
||||
if ($debug) {
|
||||
print Data::Dumper->Dump([\%ioctls], [qw(*ioctls)]) if (%ioctls);
|
||||
print Data::Dumper->Dump([\%typedefs], [qw(*typedefs)]) if (%typedefs);
|
||||
print Data::Dumper->Dump([\%enums], [qw(*enums)]) if (%enums);
|
||||
print Data::Dumper->Dump([\%structs], [qw(*structs)]) if (%structs);
|
||||
print Data::Dumper->Dump([\%defines], [qw(*defines)]) if (%defines);
|
||||
print Data::Dumper->Dump([\%enum_symbols], [qw(*enum_symbols)]) if (%enum_symbols);
|
||||
}
|
||||
|
||||
#
|
||||
# Align block
|
||||
#
|
||||
$data = expand($data);
|
||||
$data = " " . $data;
|
||||
$data =~ s/\n/\n /g;
|
||||
$data =~ s/\n\s+$/\n/g;
|
||||
$data =~ s/\n\s+\n/\n\n/g;
|
||||
|
||||
#
|
||||
# Add escape codes for special characters
|
||||
#
|
||||
$data =~ s,([\_\`\*\<\>\&\\\\:\/\|\%\$\#\{\}\~\^]),\\$1,g;
|
||||
|
||||
$data =~ s,DEPRECATED,**DEPRECATED**,g;
|
||||
|
||||
#
|
||||
# Add references
|
||||
#
|
||||
|
||||
my $start_delim = "[ \n\t\(\=\*\@]";
|
||||
my $end_delim = "(\\s|,|\\\\=|\\\\:|\\;|\\\)|\\}|\\{)";
|
||||
|
||||
foreach my $r (keys %ioctls) {
|
||||
my $s = $ioctls{$r};
|
||||
|
||||
$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
|
||||
|
||||
print "$r -> $s\n" if ($debug);
|
||||
|
||||
$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
|
||||
}
|
||||
|
||||
foreach my $r (keys %defines) {
|
||||
my $s = $defines{$r};
|
||||
|
||||
$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
|
||||
|
||||
print "$r -> $s\n" if ($debug);
|
||||
|
||||
$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
|
||||
}
|
||||
|
||||
foreach my $r (keys %enum_symbols) {
|
||||
my $s = $enum_symbols{$r};
|
||||
|
||||
$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
|
||||
|
||||
print "$r -> $s\n" if ($debug);
|
||||
|
||||
$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
|
||||
}
|
||||
|
||||
foreach my $r (keys %enums) {
|
||||
my $s = $enums{$r};
|
||||
|
||||
$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
|
||||
|
||||
print "$r -> $s\n" if ($debug);
|
||||
|
||||
$data =~ s/enum\s+($r)$end_delim/$s$2/g;
|
||||
}
|
||||
|
||||
foreach my $r (keys %structs) {
|
||||
my $s = $structs{$r};
|
||||
|
||||
$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
|
||||
|
||||
print "$r -> $s\n" if ($debug);
|
||||
|
||||
$data =~ s/struct\s+($r)$end_delim/$s$2/g;
|
||||
}
|
||||
|
||||
foreach my $r (keys %typedefs) {
|
||||
my $s = $typedefs{$r};
|
||||
|
||||
$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
|
||||
|
||||
print "$r -> $s\n" if ($debug);
|
||||
$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
|
||||
}
|
||||
|
||||
$data =~ s/\\ ([\n\s])/\1/g;
|
||||
|
||||
#
|
||||
# Generate output file
|
||||
#
|
||||
|
||||
my $title = $file_in;
|
||||
$title =~ s,.*/,,;
|
||||
|
||||
open OUT, "> $file_out" or die "Can't open $file_out";
|
||||
print OUT ".. -*- coding: utf-8; mode: rst -*-\n\n";
|
||||
print OUT "$title\n";
|
||||
print OUT "=" x length($title);
|
||||
print OUT "\n\n.. parsed-literal::\n\n";
|
||||
print OUT $data;
|
||||
close OUT;
|
||||
|
||||
__END__
|
||||
|
||||
=head1 NAME
|
||||
|
||||
parse_headers.pl - parse a C file, in order to identify functions, structs,
|
||||
enums and defines and create cross-references to a Sphinx book.
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<parse_headers.pl> [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
|
||||
|
||||
Where <options> can be: --debug, --help or --man.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 8
|
||||
|
||||
=item B<--debug>
|
||||
|
||||
Put the script in verbose mode, useful for debugging.
|
||||
|
||||
=item B<--usage>
|
||||
|
||||
Prints a brief help message and exits.
|
||||
|
||||
=item B<--help>
|
||||
|
||||
Prints a more detailed help message and exits.
|
||||
|
||||
=back
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Convert a C header or source file (C_FILE), into a ReStructured Text
|
||||
included via ..parsed-literal block with cross-references for the
|
||||
documentation files that describe the API. It accepts an optional
|
||||
EXCEPTIONS_FILE with describes what elements will be either ignored or
|
||||
be pointed to a non-default reference.
|
||||
|
||||
The output is written at the (OUT_FILE).
|
||||
|
||||
It is capable of identifying defines, functions, structs, typedefs,
|
||||
enums and enum symbols and create cross-references for all of them.
|
||||
It is also capable of distinguish #define used for specifying a Linux
|
||||
ioctl.
|
||||
|
||||
The EXCEPTIONS_FILE contain two rules to allow ignoring a symbol or
|
||||
to replace the default references by a custom one.
|
||||
|
||||
Please read Documentation/doc-guide/parse-headers.rst at the Kernel's
|
||||
tree for more details.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.
|
||||
|
||||
License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
|
||||
|
||||
This is free software: you are free to change and redistribute it.
|
||||
There is NO WARRANTY, to the extent permitted by law.
|
||||
|
||||
=cut
|
||||
3
Documentation/sphinx/requirements.txt
Normal file
3
Documentation/sphinx/requirements.txt
Normal file
@ -0,0 +1,3 @@
|
||||
docutils==0.12
|
||||
Sphinx==1.4.9
|
||||
sphinx_rtd_theme
|
||||
376
Documentation/sphinx/rstFlatTable.py
Executable file
376
Documentation/sphinx/rstFlatTable.py
Executable file
@ -0,0 +1,376 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8; mode: python -*-
|
||||
# pylint: disable=C0330, R0903, R0912
|
||||
|
||||
u"""
|
||||
flat-table
|
||||
~~~~~~~~~~
|
||||
|
||||
Implementation of the ``flat-table`` reST-directive.
|
||||
|
||||
:copyright: Copyright (C) 2016 Markus Heiser
|
||||
:license: GPL Version 2, June 1991 see linux/COPYING for details.
|
||||
|
||||
The ``flat-table`` (:py:class:`FlatTable`) is a double-stage list similar to
|
||||
the ``list-table`` with some additional features:
|
||||
|
||||
* *column-span*: with the role ``cspan`` a cell can be extended through
|
||||
additional columns
|
||||
|
||||
* *row-span*: with the role ``rspan`` a cell can be extended through
|
||||
additional rows
|
||||
|
||||
* *auto span* rightmost cell of a table row over the missing cells on the
|
||||
right side of that table-row. With Option ``:fill-cells:`` this behavior
|
||||
can changed from *auto span* to *auto fill*, which automaticly inserts
|
||||
(empty) cells instead of spanning the last cell.
|
||||
|
||||
Options:
|
||||
|
||||
* header-rows: [int] count of header rows
|
||||
* stub-columns: [int] count of stub columns
|
||||
* widths: [[int] [int] ... ] widths of columns
|
||||
* fill-cells: instead of autospann missing cells, insert missing cells
|
||||
|
||||
roles:
|
||||
|
||||
* cspan: [int] additionale columns (*morecols*)
|
||||
* rspan: [int] additionale rows (*morerows*)
|
||||
"""
|
||||
|
||||
# ==============================================================================
|
||||
# imports
|
||||
# ==============================================================================
|
||||
|
||||
import sys
|
||||
|
||||
from docutils import nodes
|
||||
from docutils.parsers.rst import directives, roles
|
||||
from docutils.parsers.rst.directives.tables import Table
|
||||
from docutils.utils import SystemMessagePropagation
|
||||
|
||||
# ==============================================================================
|
||||
# common globals
|
||||
# ==============================================================================
|
||||
|
||||
# The version numbering follows numbering of the specification
|
||||
# (Documentation/books/kernel-doc-HOWTO).
|
||||
__version__ = '1.0'
|
||||
|
||||
PY3 = sys.version_info[0] == 3
|
||||
PY2 = sys.version_info[0] == 2
|
||||
|
||||
if PY3:
|
||||
# pylint: disable=C0103, W0622
|
||||
unicode = str
|
||||
basestring = str
|
||||
|
||||
# ==============================================================================
|
||||
def setup(app):
|
||||
# ==============================================================================
|
||||
|
||||
app.add_directive("flat-table", FlatTable)
|
||||
roles.register_local_role('cspan', c_span)
|
||||
roles.register_local_role('rspan', r_span)
|
||||
|
||||
return dict(
|
||||
version = __version__,
|
||||
parallel_read_safe = True,
|
||||
parallel_write_safe = True
|
||||
)
|
||||
|
||||
# ==============================================================================
|
||||
def c_span(name, rawtext, text, lineno, inliner, options=None, content=None):
|
||||
# ==============================================================================
|
||||
# pylint: disable=W0613
|
||||
|
||||
options = options if options is not None else {}
|
||||
content = content if content is not None else []
|
||||
nodelist = [colSpan(span=int(text))]
|
||||
msglist = []
|
||||
return nodelist, msglist
|
||||
|
||||
# ==============================================================================
|
||||
def r_span(name, rawtext, text, lineno, inliner, options=None, content=None):
|
||||
# ==============================================================================
|
||||
# pylint: disable=W0613
|
||||
|
||||
options = options if options is not None else {}
|
||||
content = content if content is not None else []
|
||||
nodelist = [rowSpan(span=int(text))]
|
||||
msglist = []
|
||||
return nodelist, msglist
|
||||
|
||||
|
||||
# ==============================================================================
|
||||
class rowSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
|
||||
class colSpan(nodes.General, nodes.Element): pass # pylint: disable=C0103,C0321
|
||||
# ==============================================================================
|
||||
|
||||
# ==============================================================================
|
||||
class FlatTable(Table):
|
||||
# ==============================================================================
|
||||
|
||||
u"""FlatTable (``flat-table``) directive"""
|
||||
|
||||
option_spec = {
|
||||
'name': directives.unchanged
|
||||
, 'class': directives.class_option
|
||||
, 'header-rows': directives.nonnegative_int
|
||||
, 'stub-columns': directives.nonnegative_int
|
||||
, 'widths': directives.positive_int_list
|
||||
, 'fill-cells' : directives.flag }
|
||||
|
||||
def run(self):
|
||||
|
||||
if not self.content:
|
||||
error = self.state_machine.reporter.error(
|
||||
'The "%s" directive is empty; content required.' % self.name,
|
||||
nodes.literal_block(self.block_text, self.block_text),
|
||||
line=self.lineno)
|
||||
return [error]
|
||||
|
||||
title, messages = self.make_title()
|
||||
node = nodes.Element() # anonymous container for parsing
|
||||
self.state.nested_parse(self.content, self.content_offset, node)
|
||||
|
||||
tableBuilder = ListTableBuilder(self)
|
||||
tableBuilder.parseFlatTableNode(node)
|
||||
tableNode = tableBuilder.buildTableNode()
|
||||
# SDK.CONSOLE() # print --> tableNode.asdom().toprettyxml()
|
||||
if title:
|
||||
tableNode.insert(0, title)
|
||||
return [tableNode] + messages
|
||||
|
||||
|
||||
# ==============================================================================
|
||||
class ListTableBuilder(object):
|
||||
# ==============================================================================
|
||||
|
||||
u"""Builds a table from a double-stage list"""
|
||||
|
||||
def __init__(self, directive):
|
||||
self.directive = directive
|
||||
self.rows = []
|
||||
self.max_cols = 0
|
||||
|
||||
def buildTableNode(self):
|
||||
|
||||
colwidths = self.directive.get_column_widths(self.max_cols)
|
||||
if isinstance(colwidths, tuple):
|
||||
# Since docutils 0.13, get_column_widths returns a (widths,
|
||||
# colwidths) tuple, where widths is a string (i.e. 'auto').
|
||||
# See https://sourceforge.net/p/docutils/patches/120/.
|
||||
colwidths = colwidths[1]
|
||||
stub_columns = self.directive.options.get('stub-columns', 0)
|
||||
header_rows = self.directive.options.get('header-rows', 0)
|
||||
|
||||
table = nodes.table()
|
||||
tgroup = nodes.tgroup(cols=len(colwidths))
|
||||
table += tgroup
|
||||
|
||||
|
||||
for colwidth in colwidths:
|
||||
colspec = nodes.colspec(colwidth=colwidth)
|
||||
# FIXME: It seems, that the stub method only works well in the
|
||||
# absence of rowspan (observed by the html buidler, the docutils-xml
|
||||
# build seems OK). This is not extraordinary, because there exists
|
||||
# no table directive (except *this* flat-table) which allows to
|
||||
# define coexistent of rowspan and stubs (there was no use-case
|
||||
# before flat-table). This should be reviewed (later).
|
||||
if stub_columns:
|
||||
colspec.attributes['stub'] = 1
|
||||
stub_columns -= 1
|
||||
tgroup += colspec
|
||||
stub_columns = self.directive.options.get('stub-columns', 0)
|
||||
|
||||
if header_rows:
|
||||
thead = nodes.thead()
|
||||
tgroup += thead
|
||||
for row in self.rows[:header_rows]:
|
||||
thead += self.buildTableRowNode(row)
|
||||
|
||||
tbody = nodes.tbody()
|
||||
tgroup += tbody
|
||||
|
||||
for row in self.rows[header_rows:]:
|
||||
tbody += self.buildTableRowNode(row)
|
||||
return table
|
||||
|
||||
def buildTableRowNode(self, row_data, classes=None):
|
||||
classes = [] if classes is None else classes
|
||||
row = nodes.row()
|
||||
for cell in row_data:
|
||||
if cell is None:
|
||||
continue
|
||||
cspan, rspan, cellElements = cell
|
||||
|
||||
attributes = {"classes" : classes}
|
||||
if rspan:
|
||||
attributes['morerows'] = rspan
|
||||
if cspan:
|
||||
attributes['morecols'] = cspan
|
||||
entry = nodes.entry(**attributes)
|
||||
entry.extend(cellElements)
|
||||
row += entry
|
||||
return row
|
||||
|
||||
def raiseError(self, msg):
|
||||
error = self.directive.state_machine.reporter.error(
|
||||
msg
|
||||
, nodes.literal_block(self.directive.block_text
|
||||
, self.directive.block_text)
|
||||
, line = self.directive.lineno )
|
||||
raise SystemMessagePropagation(error)
|
||||
|
||||
def parseFlatTableNode(self, node):
|
||||
u"""parses the node from a :py:class:`FlatTable` directive's body"""
|
||||
|
||||
if len(node) != 1 or not isinstance(node[0], nodes.bullet_list):
|
||||
self.raiseError(
|
||||
'Error parsing content block for the "%s" directive: '
|
||||
'exactly one bullet list expected.' % self.directive.name )
|
||||
|
||||
for rowNum, rowItem in enumerate(node[0]):
|
||||
row = self.parseRowItem(rowItem, rowNum)
|
||||
self.rows.append(row)
|
||||
self.roundOffTableDefinition()
|
||||
|
||||
def roundOffTableDefinition(self):
|
||||
u"""Round off the table definition.
|
||||
|
||||
This method rounds off the table definition in :py:member:`rows`.
|
||||
|
||||
* This method inserts the needed ``None`` values for the missing cells
|
||||
arising from spanning cells over rows and/or columns.
|
||||
|
||||
* recount the :py:member:`max_cols`
|
||||
|
||||
* Autospan or fill (option ``fill-cells``) missing cells on the right
|
||||
side of the table-row
|
||||
"""
|
||||
|
||||
y = 0
|
||||
while y < len(self.rows):
|
||||
x = 0
|
||||
|
||||
while x < len(self.rows[y]):
|
||||
cell = self.rows[y][x]
|
||||
if cell is None:
|
||||
x += 1
|
||||
continue
|
||||
cspan, rspan = cell[:2]
|
||||
# handle colspan in current row
|
||||
for c in range(cspan):
|
||||
try:
|
||||
self.rows[y].insert(x+c+1, None)
|
||||
except: # pylint: disable=W0702
|
||||
# the user sets ambiguous rowspans
|
||||
pass # SDK.CONSOLE()
|
||||
# handle colspan in spanned rows
|
||||
for r in range(rspan):
|
||||
for c in range(cspan + 1):
|
||||
try:
|
||||
self.rows[y+r+1].insert(x+c, None)
|
||||
except: # pylint: disable=W0702
|
||||
# the user sets ambiguous rowspans
|
||||
pass # SDK.CONSOLE()
|
||||
x += 1
|
||||
y += 1
|
||||
|
||||
# Insert the missing cells on the right side. For this, first
|
||||
# re-calculate the max columns.
|
||||
|
||||
for row in self.rows:
|
||||
if self.max_cols < len(row):
|
||||
self.max_cols = len(row)
|
||||
|
||||
# fill with empty cells or cellspan?
|
||||
|
||||
fill_cells = False
|
||||
if 'fill-cells' in self.directive.options:
|
||||
fill_cells = True
|
||||
|
||||
for row in self.rows:
|
||||
x = self.max_cols - len(row)
|
||||
if x and not fill_cells:
|
||||
if row[-1] is None:
|
||||
row.append( ( x - 1, 0, []) )
|
||||
else:
|
||||
cspan, rspan, content = row[-1]
|
||||
row[-1] = (cspan + x, rspan, content)
|
||||
elif x and fill_cells:
|
||||
for i in range(x):
|
||||
row.append( (0, 0, nodes.comment()) )
|
||||
|
||||
def pprint(self):
|
||||
# for debugging
|
||||
retVal = "[ "
|
||||
for row in self.rows:
|
||||
retVal += "[ "
|
||||
for col in row:
|
||||
if col is None:
|
||||
retVal += ('%r' % col)
|
||||
retVal += "\n , "
|
||||
else:
|
||||
content = col[2][0].astext()
|
||||
if len (content) > 30:
|
||||
content = content[:30] + "..."
|
||||
retVal += ('(cspan=%s, rspan=%s, %r)'
|
||||
% (col[0], col[1], content))
|
||||
retVal += "]\n , "
|
||||
retVal = retVal[:-2]
|
||||
retVal += "]\n , "
|
||||
retVal = retVal[:-2]
|
||||
return retVal + "]"
|
||||
|
||||
def parseRowItem(self, rowItem, rowNum):
|
||||
row = []
|
||||
childNo = 0
|
||||
error = False
|
||||
cell = None
|
||||
target = None
|
||||
|
||||
for child in rowItem:
|
||||
if (isinstance(child , nodes.comment)
|
||||
or isinstance(child, nodes.system_message)):
|
||||
pass
|
||||
elif isinstance(child , nodes.target):
|
||||
target = child
|
||||
elif isinstance(child, nodes.bullet_list):
|
||||
childNo += 1
|
||||
cell = child
|
||||
else:
|
||||
error = True
|
||||
break
|
||||
|
||||
if childNo != 1 or error:
|
||||
self.raiseError(
|
||||
'Error parsing content block for the "%s" directive: '
|
||||
'two-level bullet list expected, but row %s does not '
|
||||
'contain a second-level bullet list.'
|
||||
% (self.directive.name, rowNum + 1))
|
||||
|
||||
for cellItem in cell:
|
||||
cspan, rspan, cellElements = self.parseCellItem(cellItem)
|
||||
if target is not None:
|
||||
cellElements.insert(0, target)
|
||||
row.append( (cspan, rspan, cellElements) )
|
||||
return row
|
||||
|
||||
def parseCellItem(self, cellItem):
|
||||
# search and remove cspan, rspan colspec from the first element in
|
||||
# this listItem (field).
|
||||
cspan = rspan = 0
|
||||
if not len(cellItem):
|
||||
return cspan, rspan, []
|
||||
for elem in cellItem[0]:
|
||||
if isinstance(elem, colSpan):
|
||||
cspan = elem.get("span")
|
||||
elem.parent.remove(elem)
|
||||
continue
|
||||
if isinstance(elem, rowSpan):
|
||||
rspan = elem.get("span")
|
||||
elem.parent.remove(elem)
|
||||
continue
|
||||
return cspan, rspan, cellItem[:]
|
||||
8
Makefile
8
Makefile
@ -1707,9 +1707,11 @@ tests:
|
||||
|
||||
# Documentation targets
|
||||
# ---------------------------------------------------------------------------
|
||||
%docs: scripts_basic FORCE
|
||||
$(Q)$(MAKE) $(build)=scripts build_docproc
|
||||
$(Q)$(MAKE) $(build)=doc/DocBook $@
|
||||
DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
|
||||
linkcheckdocs dochelp refcheckdocs
|
||||
PHONY += $(DOC_TARGETS)
|
||||
$(DOC_TARGETS): scripts_basic FORCE
|
||||
$(Q)$(MAKE) $(build)=Documentation $@
|
||||
|
||||
endif #ifeq ($(config-targets),1)
|
||||
endif #ifeq ($(mixed-targets),1)
|
||||
|
||||
15
doc/DocBook/.gitignore
vendored
15
doc/DocBook/.gitignore
vendored
@ -1,15 +0,0 @@
|
||||
*.xml
|
||||
*.ps
|
||||
*.pdf
|
||||
*.html
|
||||
*.9.gz
|
||||
*.9
|
||||
*.aux
|
||||
*.dvi
|
||||
*.log
|
||||
*.out
|
||||
*.png
|
||||
*.gif
|
||||
*.svg
|
||||
media-indices.tmpl
|
||||
media-entities.tmpl
|
||||
@ -1,222 +0,0 @@
|
||||
# SPDX-License-Identifier: GPL-2.0
|
||||
###
|
||||
# This makefile is used to generate the kernel documentation,
|
||||
# primarily based on in-line comments in various source files.
|
||||
# See Documentation/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.
|
||||
|
||||
DOCBOOKS := efi.xml linker_lists.xml stdio.xml
|
||||
|
||||
###
|
||||
# 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 += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs
|
||||
|
||||
targets += $(DOCBOOKS)
|
||||
BOOKS := $(addprefix $(obj)/,$(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)
|
||||
$(if $(wildcard $(obj)/man/*.9),gzip -f $(obj)/man/*.9)
|
||||
|
||||
installmandocs: mandocs
|
||||
mkdir -p /usr/local/man/man9/
|
||||
install $(obj)/man/*.9.gz /usr/local/man/man9/
|
||||
|
||||
###
|
||||
#External programs used
|
||||
KERNELDOC = $(srctree)/scripts/kernel-doc
|
||||
DOCPROC = $(objtree)/scripts/docproc
|
||||
|
||||
XMLTOFLAGS = -m $(srctree)/$(src)/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).
|
||||
quiet_cmd_docproc = DOCPROC $@
|
||||
cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
|
||||
define rule_docproc
|
||||
set -e; \
|
||||
$(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \
|
||||
$(cmd_$(1)); \
|
||||
( \
|
||||
echo 'cmd_$@ := $(cmd_$(1))'; \
|
||||
echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; \
|
||||
) > $(dir $@).$(notdir $@).cmd
|
||||
endef
|
||||
|
||||
%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) FORCE
|
||||
$(call if_changed_rule,docproc)
|
||||
|
||||
# Tell kbuild to always build the programs
|
||||
always := $(hostprogs-y)
|
||||
|
||||
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 = $(obj)/$(index)
|
||||
build_main_index = rm -rf $(main_idx); \
|
||||
echo '<h1>U-Boot Bootloader HTML Documentation</h1>' >> $(main_idx) && \
|
||||
echo '<h2>U-Boot Version: $(UBOOTVERSION)</h2>' >> $(main_idx) && \
|
||||
cat $(HTML) >> $(main_idx)
|
||||
|
||||
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 $< ; 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:
|
||||
$(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)
|
||||
@ -1,16 +0,0 @@
|
||||
body {
|
||||
font-family: sans-serif;
|
||||
}
|
||||
|
||||
.programlisting {
|
||||
font-family: monospace;
|
||||
font-size: 1em;
|
||||
display: block;
|
||||
padding: 10px;
|
||||
border: 1px solid #aaa;
|
||||
color: #000;
|
||||
background-color: #eee;
|
||||
overflow: auto;
|
||||
margin: 1em 0em;
|
||||
border-radius: 6px;
|
||||
}
|
||||
@ -1,17 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||
|
||||
<book id="UBootEFI">
|
||||
<bookinfo>
|
||||
<title>The U-Boot EFI subsystem</title>
|
||||
</bookinfo>
|
||||
|
||||
<toc></toc>
|
||||
|
||||
<chapter id="BootServices">
|
||||
<title>Boot services</title>
|
||||
!Ilib/efi_loader/efi_boottime.c
|
||||
</chapter>
|
||||
|
||||
</book>
|
||||
@ -1,46 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||
|
||||
<book id="UBootLGArrays">
|
||||
<bookinfo>
|
||||
<title>The U-Boot Linker-Generated Arrays</title>
|
||||
|
||||
<legalnotice>
|
||||
<para>
|
||||
This documentation 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For more details see the file COPYING in the source
|
||||
distribution of U-Boot Bootloader.
|
||||
</para>
|
||||
</legalnotice>
|
||||
</bookinfo>
|
||||
|
||||
<toc></toc>
|
||||
|
||||
<chapter id="adt">
|
||||
<title>Linker-Generated Arrays</title>
|
||||
!Iinclude/linker_lists.h
|
||||
</chapter>
|
||||
|
||||
</book>
|
||||
@ -1,46 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||
|
||||
<book id="UBootSTDIO">
|
||||
<bookinfo>
|
||||
<title>The U-Boot STDIO subsystem</title>
|
||||
|
||||
<legalnotice>
|
||||
<para>
|
||||
This documentation 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For more details see the file COPYING in the source
|
||||
distribution of U-Boot Bootloader.
|
||||
</para>
|
||||
</legalnotice>
|
||||
</bookinfo>
|
||||
|
||||
<toc></toc>
|
||||
|
||||
<chapter id="adt">
|
||||
<title>U-Boot Serial subsystem</title>
|
||||
!Idrivers/serial/serial.c
|
||||
</chapter>
|
||||
|
||||
</book>
|
||||
@ -1,10 +0,0 @@
|
||||
<?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>
|
||||
@ -19,87 +19,6 @@
|
||||
|
||||
#if !defined(__ASSEMBLY__)
|
||||
|
||||
/**
|
||||
* A linker list is constructed by grouping together linker input
|
||||
* sections, each containing one entry of the list. Each input section
|
||||
* contains a constant initialized variable which holds the entry's
|
||||
* content. Linker list input sections are constructed from the list
|
||||
* and entry names, plus a prefix which allows grouping all lists
|
||||
* together. Assuming _list and _entry are the list and entry names,
|
||||
* then the corresponding input section name is
|
||||
*
|
||||
* .u_boot_list_ + 2_ + @_list + _2_ + @_entry
|
||||
*
|
||||
* and the C variable name is
|
||||
*
|
||||
* _u_boot_list + _2_ + @_list + _2_ + @_entry
|
||||
*
|
||||
* This ensures uniqueness for both input section and C variable name.
|
||||
*
|
||||
* Note that the names differ only in the first character, "." for the
|
||||
* section and "_" for the variable, so that the linker cannot confuse
|
||||
* section and symbol names. From now on, both names will be referred
|
||||
* to as
|
||||
*
|
||||
* %u_boot_list_ + 2_ + @_list + _2_ + @_entry
|
||||
*
|
||||
* Entry variables need never be referred to directly.
|
||||
*
|
||||
* The naming scheme for input sections allows grouping all linker lists
|
||||
* into a single linker output section and grouping all entries for a
|
||||
* single list.
|
||||
*
|
||||
* Note the two '_2_' constant components in the names: their presence
|
||||
* allows putting a start and end symbols around a list, by mapping
|
||||
* these symbols to sections names with components "1" (before) and
|
||||
* "3" (after) instead of "2" (within).
|
||||
* Start and end symbols for a list can generally be defined as
|
||||
*
|
||||
* %u_boot_list_2_ + @_list + _1_...
|
||||
* %u_boot_list_2_ + @_list + _3_...
|
||||
*
|
||||
* Start and end symbols for the whole of the linker lists area can be
|
||||
* defined as
|
||||
*
|
||||
* %u_boot_list_1_...
|
||||
* %u_boot_list_3_...
|
||||
*
|
||||
* Here is an example of the sorted sections which result from a list
|
||||
* "array" made up of three entries : "first", "second" and "third",
|
||||
* iterated at least once.
|
||||
*
|
||||
* .u_boot_list_2_array_1
|
||||
* .u_boot_list_2_array_2_first
|
||||
* .u_boot_list_2_array_2_second
|
||||
* .u_boot_list_2_array_2_third
|
||||
* .u_boot_list_2_array_3
|
||||
*
|
||||
* If lists must be divided into sublists (e.g. for iterating only on
|
||||
* part of a list), one can simply give the list a name of the form
|
||||
* 'outer_2_inner', where 'outer' is the global list name and 'inner'
|
||||
* is the sub-list name. Iterators for the whole list should use the
|
||||
* global list name ("outer"); iterators for only a sub-list should use
|
||||
* the full sub-list name ("outer_2_inner").
|
||||
*
|
||||
* Here is an example of the sections generated from a global list
|
||||
* named "drivers", two sub-lists named "i2c" and "pci", and iterators
|
||||
* defined for the whole list and each sub-list:
|
||||
*
|
||||
* %u_boot_list_2_drivers_1
|
||||
* %u_boot_list_2_drivers_2_i2c_1
|
||||
* %u_boot_list_2_drivers_2_i2c_2_first
|
||||
* %u_boot_list_2_drivers_2_i2c_2_first
|
||||
* %u_boot_list_2_drivers_2_i2c_2_second
|
||||
* %u_boot_list_2_drivers_2_i2c_2_third
|
||||
* %u_boot_list_2_drivers_2_i2c_3
|
||||
* %u_boot_list_2_drivers_2_pci_1
|
||||
* %u_boot_list_2_drivers_2_pci_2_first
|
||||
* %u_boot_list_2_drivers_2_pci_2_second
|
||||
* %u_boot_list_2_drivers_2_pci_2_third
|
||||
* %u_boot_list_2_drivers_2_pci_3
|
||||
* %u_boot_list_2_drivers_3
|
||||
*/
|
||||
|
||||
/**
|
||||
* llsym() - Access a linker-generated array entry
|
||||
* @_type: Data type of the entry
|
||||
@ -134,16 +53,19 @@
|
||||
* a subsection of this section is declared and contains some elements,
|
||||
* it is imperative that the elements are of the same type.
|
||||
*
|
||||
* 4) In case an outer section is declared that contains some array elements
|
||||
* 3) In case an outer section is declared that contains some array elements
|
||||
* AND an inner subsection of this section is declared and contains some
|
||||
* elements, then when traversing the outer section, even the elements of
|
||||
* the inner sections are present in the array.
|
||||
*
|
||||
* Example:
|
||||
* ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
|
||||
* .x = 3,
|
||||
* .y = 4,
|
||||
* };
|
||||
*
|
||||
* ::
|
||||
*
|
||||
* ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
|
||||
* .x = 3,
|
||||
* .y = 4,
|
||||
* };
|
||||
*/
|
||||
#define ll_entry_declare(_type, _name, _list) \
|
||||
_type _u_boot_list_2_##_list##_2_##_name __aligned(4) \
|
||||
@ -160,18 +82,20 @@
|
||||
* This is like ll_entry_declare() but creates multiple entries. It should
|
||||
* be assigned to an array.
|
||||
*
|
||||
* ll_entry_declare_list(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
|
||||
* { .x = 3, .y = 4 },
|
||||
* { .x = 8, .y = 2 },
|
||||
* { .x = 1, .y = 7 }
|
||||
* };
|
||||
* ::
|
||||
*
|
||||
* ll_entry_declare_list(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
|
||||
* { .x = 3, .y = 4 },
|
||||
* { .x = 8, .y = 2 },
|
||||
* { .x = 1, .y = 7 }
|
||||
* };
|
||||
*/
|
||||
#define ll_entry_declare_list(_type, _name, _list) \
|
||||
_type _u_boot_list_2_##_list##_2_##_name[] __aligned(4) \
|
||||
__attribute__((unused, \
|
||||
section(".u_boot_list_2_"#_list"_2_"#_name)))
|
||||
|
||||
/**
|
||||
/*
|
||||
* We need a 0-byte-size type for iterator symbols, and the compiler
|
||||
* does not allow defining objects of C type 'void'. Using an empty
|
||||
* struct is allowed by the compiler, but causes gcc versions 4.4 and
|
||||
@ -185,7 +109,7 @@
|
||||
* @_type: Data type of the entry
|
||||
* @_list: Name of the list in which this entry is placed
|
||||
*
|
||||
* This function returns (_type *) pointer to the very first entry of a
|
||||
* This function returns ``(_type *)`` pointer to the very first entry of a
|
||||
* linker-generated array placed into subsection of .u_boot_list section
|
||||
* specified by _list argument.
|
||||
*
|
||||
@ -193,7 +117,10 @@
|
||||
* must be 2 and its rightmost index must be 1.
|
||||
*
|
||||
* Example:
|
||||
* struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
|
||||
*
|
||||
* ::
|
||||
*
|
||||
* struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
|
||||
*/
|
||||
#define ll_entry_start(_type, _list) \
|
||||
({ \
|
||||
@ -208,7 +135,7 @@
|
||||
* @_list: Name of the list in which this entry is placed
|
||||
* (with underscores instead of dots)
|
||||
*
|
||||
* This function returns (_type *) pointer after the very last entry of
|
||||
* This function returns ``(_type *)`` pointer after the very last entry of
|
||||
* a linker-generated array placed into subsection of .u_boot_list
|
||||
* section specified by _list argument.
|
||||
*
|
||||
@ -216,7 +143,10 @@
|
||||
* must be 2 and its rightmost index must be 3.
|
||||
*
|
||||
* Example:
|
||||
* struct my_sub_cmd *msc = ll_entry_end(struct my_sub_cmd, cmd_sub);
|
||||
*
|
||||
* ::
|
||||
*
|
||||
* struct my_sub_cmd *msc = ll_entry_end(struct my_sub_cmd, cmd_sub);
|
||||
*/
|
||||
#define ll_entry_end(_type, _list) \
|
||||
({ \
|
||||
@ -234,11 +164,14 @@
|
||||
* argument. The result is of an unsigned int type.
|
||||
*
|
||||
* Example:
|
||||
* int i;
|
||||
* const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub);
|
||||
* struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
|
||||
* for (i = 0; i < count; i++, msc++)
|
||||
* printf("Entry %i, x=%i y=%i\n", i, msc->x, msc->y);
|
||||
*
|
||||
* ::
|
||||
*
|
||||
* int i;
|
||||
* const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub);
|
||||
* struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
|
||||
* for (i = 0; i < count; i++, msc++)
|
||||
* printf("Entry %i, x=%i y=%i\n", i, msc->x, msc->y);
|
||||
*/
|
||||
#define ll_entry_count(_type, _list) \
|
||||
({ \
|
||||
@ -259,12 +192,15 @@
|
||||
* and it's name.
|
||||
*
|
||||
* Example:
|
||||
* ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
|
||||
* .x = 3,
|
||||
* .y = 4,
|
||||
* };
|
||||
* ...
|
||||
* struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub);
|
||||
*
|
||||
* ::
|
||||
*
|
||||
* ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
|
||||
* .x = 3,
|
||||
* .y = 4,
|
||||
* };
|
||||
* ...
|
||||
* struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub);
|
||||
*/
|
||||
#define ll_entry_get(_type, _name, _list) \
|
||||
({ \
|
||||
@ -278,14 +214,17 @@
|
||||
* ll_start() - Point to first entry of first linker-generated array
|
||||
* @_type: Data type of the entry
|
||||
*
|
||||
* This function returns (_type *) pointer to the very first entry of
|
||||
* This function returns ``(_type *)`` pointer to the very first entry of
|
||||
* the very first linker-generated array.
|
||||
*
|
||||
* Since this macro defines the start of the linker-generated arrays,
|
||||
* its leftmost index must be 1.
|
||||
*
|
||||
* Example:
|
||||
* struct my_sub_cmd *msc = ll_start(struct my_sub_cmd);
|
||||
*
|
||||
* ::
|
||||
*
|
||||
* struct my_sub_cmd *msc = ll_start(struct my_sub_cmd);
|
||||
*/
|
||||
#define ll_start(_type) \
|
||||
({ \
|
||||
@ -298,14 +237,17 @@
|
||||
* ll_end() - Point after last entry of last linker-generated array
|
||||
* @_type: Data type of the entry
|
||||
*
|
||||
* This function returns (_type *) pointer after the very last entry of
|
||||
* This function returns ``(_type *)`` pointer after the very last entry of
|
||||
* the very last linker-generated array.
|
||||
*
|
||||
* Since this macro defines the end of the linker-generated arrays,
|
||||
* its leftmost index must be 3.
|
||||
*
|
||||
* Example:
|
||||
* struct my_sub_cmd *msc = ll_end(struct my_sub_cmd);
|
||||
*
|
||||
* ::
|
||||
*
|
||||
* struct my_sub_cmd *msc = ll_end(struct my_sub_cmd);
|
||||
*/
|
||||
#define ll_end(_type) \
|
||||
({ \
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
2561
scripts/kernel-doc
2561
scripts/kernel-doc
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user