diff options
| -rw-r--r-- | Documentation/DMA-API-HOWTO.txt | 6 | ||||
| -rw-r--r-- | Documentation/DocBook/Makefile | 1 | ||||
| -rw-r--r-- | Documentation/Makefile.sphinx | 11 | ||||
| -rw-r--r-- | Documentation/conf.py | 47 | ||||
| -rw-r--r-- | Documentation/driver-model/device.txt | 2 | ||||
| -rw-r--r-- | Documentation/filesystems/proc.txt | 2 | ||||
| -rw-r--r-- | Documentation/ioctl/botching-up-ioctls.txt | 13 | ||||
| -rw-r--r-- | Documentation/kernel-documentation.rst | 29 | ||||
| -rw-r--r-- | Documentation/kernel-parameters.txt | 22 | ||||
| -rw-r--r-- | Documentation/media/conf.py | 5 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-func-open.rst | 2 | ||||
| -rw-r--r-- | Documentation/media/uapi/cec/cec-ioc-dqevent.rst | 5 | ||||
| -rw-r--r-- | Documentation/scsi/scsi-parameters.txt | 2 | ||||
| -rw-r--r-- | Documentation/sphinx/cdomain.py | 165 | ||||
| -rw-r--r-- | Documentation/sphinx/kernel-doc.py | 8 | ||||
| -rwxr-xr-x | Documentation/sphinx/kernel_include.py | 7 | ||||
| -rwxr-xr-x[-rw-r--r--] | Documentation/sphinx/rstFlatTable.py | 6 | ||||
| -rw-r--r-- | Documentation/x86/x86_64/mm.txt | 6 | ||||
| -rw-r--r-- | Makefile | 2 | ||||
| -rwxr-xr-x | scripts/kernel-doc | 48 |
20 files changed, 329 insertions, 60 deletions
diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index 781024ef9050..494ffac655ee 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -931,10 +931,8 @@ to "Closing". 1) Struct scatterlist requirements. - Don't invent the architecture specific struct scatterlist; just use - <asm-generic/scatterlist.h>. You need to enable - CONFIG_NEED_SG_DMA_LENGTH if the architecture supports IOMMUs - (including software IOMMU). + You need to enable CONFIG_NEED_SG_DMA_LENGTH if the architecture + supports IOMMUs (including software IOMMU). 2) ARCH_DMA_MINALIGN diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 5fbfb7273f38..736f5916daea 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -72,6 +72,7 @@ installmandocs: mandocs # no-op for the DocBook toolchain epubdocs: +latexdocs: ### #External programs used diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index ba4efb1f68f3..92deea30b183 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -66,13 +66,17 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4); htmldocs: @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) -pdfdocs: +latexdocs: ifeq ($(HAVE_PDFLATEX),0) $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX - @$(call loop_cmd,sphinx,latex,.,latex,.) - $(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/latex + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) +endif # HAVE_PDFLATEX + +pdfdocs: latexdocs +ifneq ($(HAVE_PDFLATEX),0) + $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex) endif # HAVE_PDFLATEX epubdocs: @@ -95,6 +99,7 @@ endif # HAVE_SPHINX dochelp: @echo ' Linux kernel internal documentation in different formats (Sphinx):' @echo ' htmldocs - HTML' + @echo ' latexdocs - LaTeX' @echo ' pdfdocs - PDF' @echo ' epubdocs - EPUB' @echo ' xmldocs - XML' diff --git a/Documentation/conf.py b/Documentation/conf.py index 23e2f0bbcfc8..ab484e56e23c 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -34,7 +34,7 @@ from load_config import loadConfig # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include'] +extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain'] # The name of the math extension changed on Sphinx 1.4 if minor > 3: @@ -277,26 +277,46 @@ latex_elements = { % Allow generate some pages in landscape \\usepackage{lscape} - % Put notes in gray color and let them be inside a table - - \\definecolor{MyGray}{rgb}{0.80,0.80,0.80} - - \\makeatletter\\newenvironment{graybox}{% - \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\columnwidth}}{\\end{minipage}\\end{lrbox}% - \\colorbox{MyGray}{\\usebox{\\@tempboxa}} + % 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{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}}}% + {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}% + }% + }% }\\makeatother \\makeatletter - \\renewenvironment{notice}[2]{ - \\begin{graybox} - \\bf\\it + \\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{graybox} + \\end{coloredbox} } \\makeatother @@ -306,6 +326,9 @@ latex_elements = { \\setromanfont{DejaVu Sans} \\setmonofont{DejaVu Sans Mono} + % To allow adjusting table sizes + \\usepackage{adjustbox} + ''' } diff --git a/Documentation/driver-model/device.txt b/Documentation/driver-model/device.txt index 1e70220d20f4..2403eb856187 100644 --- a/Documentation/driver-model/device.txt +++ b/Documentation/driver-model/device.txt @@ -50,7 +50,7 @@ Attributes of devices can be exported by a device driver through sysfs. Please see Documentation/filesystems/sysfs.txt for more information on how sysfs works. -As explained in Documentation/kobject.txt, device attributes must be be +As explained in Documentation/kobject.txt, device attributes must be created before the KOBJ_ADD uevent is generated. The only way to realize that is by defining an attribute group. diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index 68080ad6a75e..fcc1ac094282 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -145,7 +145,7 @@ Table 1-1: Process specific entries in /proc symbol the task is blocked in - or "0" if not blocked. pagemap Page table stack Report full stack trace, enable via CONFIG_STACKTRACE - smaps a extension based on maps, showing the memory consumption of + smaps an extension based on maps, showing the memory consumption of each mapping and flags associated with it numa_maps an extension based on maps, showing the memory locality and binding policy as well as mem usage (in pages) of each mapping. diff --git a/Documentation/ioctl/botching-up-ioctls.txt b/Documentation/ioctl/botching-up-ioctls.txt index cc30b14791cb..36138c632f7a 100644 --- a/Documentation/ioctl/botching-up-ioctls.txt +++ b/Documentation/ioctl/botching-up-ioctls.txt @@ -34,15 +34,18 @@ will need to add a a 32-bit compat layer: 64-bit platforms do. So we always need padding to the natural size to get this right. - * Pad the entire struct to a multiple of 64-bits - the structure size will - otherwise differ on 32-bit versus 64-bit. Having a different structure size - hurts when passing arrays of structures to the kernel, or if the kernel - checks the structure size, which e.g. the drm core does. + * Pad the entire struct to a multiple of 64-bits if the structure contains + 64-bit types - the structure size will otherwise differ on 32-bit versus + 64-bit. Having a different structure size hurts when passing arrays of + structures to the kernel, or if the kernel checks the structure size, which + e.g. the drm core does. * Pointers are __u64, cast from/to a uintprt_t on the userspace side and from/to a void __user * in the kernel. Try really hard not to delay this conversion or worse, fiddle the raw __u64 through your code since that - diminishes the checking tools like sparse can provide. + diminishes the checking tools like sparse can provide. The macro + u64_to_user_ptr can be used in the kernel to avoid warnings about integers + and pointres of different sizes. Basics diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst index c4eb5049da39..bc4c3f526816 100644 --- a/Documentation/kernel-documentation.rst +++ b/Documentation/kernel-documentation.rst @@ -107,6 +107,35 @@ Here are some specific guidelines for the kernel documentation: the order as encountered."), having the higher levels the same overall makes it easier to follow the documents. + +the C domain +------------ + +The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a +function prototype: + +.. code-block:: rst + + .. c:function:: int ioctl( int fd, int request ) + +The C domain of the kernel-doc has some additional features. E.g. you can +*rename* the reference name of a function with a common name like ``open`` or +``ioctl``: + +.. code-block:: rst + + .. 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 index entry for this function is also +changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by: + +.. code-block:: rst + + :c:func:`VIDIOC_LOG_STATUS` + + list tables ----------- diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 20557efa8bce..861f57514fbd 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -2161,10 +2161,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. than or equal to this physical address is ignored. maxcpus= [SMP] Maximum number of processors that an SMP kernel - should make use of. maxcpus=n : n >= 0 limits the - kernel to using 'n' processors. n=0 is a special case, - it is equivalent to "nosmp", which also disables - the IO APIC. + will bring up during bootup. maxcpus=n : n >= 0 limits + the kernel to bring up 'n' processors. Surely after + bootup you can bring up the other plugged cpu by executing + "echo 1 > /sys/devices/system/cpu/cpuX/online". So maxcpus + only takes effect during system bootup. + While n=0 is a special case, it is equivalent to "nosmp", + which also disables the IO APIC. max_loop= [LOOP] The number of loop block devices that get (loop.max_loop) unconditionally pre-created at init time. The default @@ -2571,8 +2574,6 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nodelayacct [KNL] Disable per-task delay accounting - nodisconnect [HW,SCSI,M68K] Disables SCSI disconnects. - nodsp [SH] Disable hardware DSP at boot time. noefi Disable EFI runtime services support. @@ -2773,9 +2774,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nr_cpus= [SMP] Maximum number of processors that an SMP kernel could support. nr_cpus=n : n >= 1 limits the kernel to - supporting 'n' processors. Later in runtime you can not - use hotplug cpu feature to put more cpu back to online. - just like you compile the kernel NR_CPUS=n + support 'n' processors. It could be larger than the + number of already plugged CPU during bootup, later in + runtime you can physically add extra cpu until it reaches + n. So during boot up some boot time memory for per-cpu + variables need be pre-allocated for later physical cpu + hot plugging. nr_uarts= [SERIAL] maximum number of UARTs to be registered. diff --git a/Documentation/media/conf.py b/Documentation/media/conf.py index 77cb2bbd9461..bef927bc4659 100644 --- a/Documentation/media/conf.py +++ b/Documentation/media/conf.py @@ -3,3 +3,8 @@ project = 'Linux Media Subsystem Documentation' tags.add("subproject") + +latex_documents = [ + ('index', 'media.tex', 'Linux Media Subsystem Documentation', + 'The kernel development community', 'manual'), +] diff --git a/Documentation/media/uapi/cec/cec-func-open.rst b/Documentation/media/uapi/cec/cec-func-open.rst index 38fd7e0cfccd..7c0f981a6e07 100644 --- a/Documentation/media/uapi/cec/cec-func-open.rst +++ b/Documentation/media/uapi/cec/cec-func-open.rst @@ -32,7 +32,7 @@ Arguments Open flags. Access mode must be ``O_RDWR``. When the ``O_NONBLOCK`` flag is given, the - :ref:`CEC_RECEIVE <CEC_RECEIVE>` and :ref:`CEC_DQEVENT <CEC_DQEVENT>` ioctls + :ref:`CEC_RECEIVE <CEC_RECEIVE>` and :c:func:`CEC_DQEVENT` ioctls will return the ``EAGAIN`` error code when no message or event is available, and ioctls :ref:`CEC_TRANSMIT <CEC_TRANSMIT>`, :ref:`CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` and diff --git a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst index 7a6d6d00ce19..4e12e6cd88ee 100644 --- a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst +++ b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst @@ -15,7 +15,8 @@ CEC_DQEVENT - Dequeue a CEC event Synopsis ======== -.. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp ) +.. c:function:: int ioctl( int fd, int request, struct cec_event *argp ) + :name: CEC_DQEVENT Arguments ========= @@ -36,7 +37,7 @@ Description and is currently only available as a staging kernel module. CEC devices can send asynchronous events. These can be retrieved by -calling :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>`. If the file descriptor is in +calling :c:func:`CEC_DQEVENT`. If the file descriptor is in non-blocking mode and no event is pending, then it will return -1 and set errno to the ``EAGAIN`` error code. diff --git a/Documentation/scsi/scsi-parameters.txt b/Documentation/scsi/scsi-parameters.txt index 1241ac11edb1..d5ae6ced6be3 100644 --- a/Documentation/scsi/scsi-parameters.txt +++ b/Documentation/scsi/scsi-parameters.txt @@ -79,8 +79,6 @@ parameters may be changed at runtime by the command ncr53c8xx= [HW,SCSI] - nodisconnect [HW,SCSI,M68K] Disables SCSI disconnects. - osst= [HW,SCSI] SCSI Tape Driver Format: <buffer_size>,<write_threshold> See also Documentation/scsi/st.txt. diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py new file mode 100644 index 000000000000..df0419c62096 --- /dev/null +++ b/Documentation/sphinx/cdomain.py @@ -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 = map(int, sphinx.__version__.split(".")) + +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, + } diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py index f6920c0af6ee..d15e07f36881 100644 --- a/Documentation/sphinx/kernel-doc.py +++ b/Documentation/sphinx/kernel-doc.py @@ -39,6 +39,8 @@ from docutils.parsers.rst import directives from sphinx.util.compat import Directive from sphinx.ext.autodoc import AutodocReporter +__version__ = '1.0' + class KernelDocDirective(Directive): """Extract kernel-doc comments from the specified file""" required_argument = 1 @@ -139,3 +141,9 @@ def setup(app): 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 + ) diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py index db5738238733..f523aa68a36b 100755 --- a/Documentation/sphinx/kernel_include.py +++ b/Documentation/sphinx/kernel_include.py @@ -39,11 +39,18 @@ 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): diff --git a/Documentation/sphinx/rstFlatTable.py b/Documentation/sphinx/rstFlatTable.py index 26db852e3c74..55f275793028 100644..100755 --- a/Documentation/sphinx/rstFlatTable.py +++ b/Documentation/sphinx/rstFlatTable.py @@ -73,6 +73,12 @@ def setup(app): 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): # ============================================================================== diff --git a/Documentation/x86/x86_64/mm.txt b/Documentation/x86/x86_64/mm.txt index 8c7dd5957ae1..5724092db811 100644 --- a/Documentation/x86/x86_64/mm.txt +++ b/Documentation/x86/x86_64/mm.txt @@ -12,13 +12,13 @@ ffffc90000000000 - ffffe8ffffffffff (=45 bits) vmalloc/ioremap space ffffe90000000000 - ffffe9ffffffffff (=40 bits) hole ffffea0000000000 - ffffeaffffffffff (=40 bits) virtual memory map (1TB) ... unused hole ... -ffffec0000000000 - fffffc0000000000 (=44 bits) kasan shadow memory (16TB) +ffffec0000000000 - fffffbffffffffff (=44 bits) kasan shadow memory (16TB) ... unused hole ... ffffff0000000000 - ffffff7fffffffff (=39 bits) %esp fixup stacks ... unused hole ... -ffffffef00000000 - ffffffff00000000 (=64 GB) EFI region mapping space +ffffffef00000000 - fffffffeffffffff (=64 GB) EFI region mapping space ... unused hole ... -ffffffff80000000 - ffffffffa0000000 (=512 MB) kernel text mapping, from phys 0 +ffffffff80000000 - ffffffff9fffffff (=512 MB) kernel text mapping, from phys 0 ffffffffa0000000 - ffffffffff5fffff (=1526 MB) module mapping space ffffffffff600000 - ffffffffffdfffff (=8 MB) vsyscalls ffffffffffe00000 - ffffffffffffffff (=2 MB) unused hole @@ -1432,7 +1432,7 @@ $(help-board-dirs): help-%: # Documentation targets # --------------------------------------------------------------------------- -DOC_TARGETS := xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs +DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs PHONY += $(DOC_TARGETS) $(DOC_TARGETS): scripts_basic FORCE $(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 4f2e9049e8fa..93721f3c91bf 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -212,6 +212,7 @@ my $anon_struct_union = 0; my $type_constant = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; my $type_param = '\@(\w+)'; +my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params my $type_struct = '\&((struct\s*)*[_\w]+)'; my $type_struct_xml = '\\&((struct\s*)*[_\w]+)'; my $type_env = '(\$\w+)'; @@ -292,6 +293,7 @@ my @highlights_rst = ( # Note: need to escape () to avoid func matching later [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"], [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"], + [$type_fp_param, "**\$1\\\\(\\\\)**"], [$type_func, "\\:c\\:func\\:`\$1()`"], [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], @@ -412,7 +414,7 @@ my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section names my $doc_sect = $doc_com . - '\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)'; + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; @@ -1831,13 +1833,22 @@ sub output_function_rst(%) { my %args = %{$_[0]}; my ($parameter, $section); my $oldprefix = $lineprefix; - my $start; - - print ".. c:function:: "; + my $start = ""; + + if ($args{'typedef'}) { + print ".. c:type:: ". $args{'function'} . "\n\n"; + print_lineno($declaration_start_line); + print " **Typedef**: "; + $lineprefix = ""; + output_highlight_rst($args{'purpose'}); + $start = "\n\n**Syntax**\n\n ``"; + } else { + print ".. c:function:: "; + } if ($args{'functiontype'} ne "") { - $start = $args{'functiontype'} . " " . $args{'function'} . " ("; + $start .= $args{'functiontype'} . " " . $args{'function'} . " ("; } else { - $start = $args{'function'} . " ("; + $start .= $args{'function'} . " ("; } print $start; @@ -1849,9 +1860,6 @@ sub output_function_rst(%) { $count++; $type = $args{'parametertypes'}{$parameter}; - # RST doesn't like address_space tags at function prototypes - $type =~ s/__(user|kernel|iomem|percpu|pmem|rcu)\s*//; - if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { # pointer-to-function print $1 . $parameter . ") (" . $2; @@ -1859,11 +1867,15 @@ sub output_function_rst(%) { print $type . " " . $parameter; } } - print ")\n\n"; - print_lineno($declaration_start_line); - $lineprefix = " "; - output_highlight_rst($args{'purpose'}); - print "\n"; + if ($args{'typedef'}) { + print ");``\n\n"; + } else { + print ")\n\n"; + print_lineno($declaration_start_line); + $lineprefix = " "; + output_highlight_rst($args{'purpose'}); + print "\n"; + } print "**Parameters**\n\n"; $lineprefix = " "; @@ -2003,7 +2015,7 @@ sub output_struct_rst(%) { ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type = $args{'parametertypes'}{$parameter}; print_lineno($parameterdesc_start_lines{$parameter_name}); - print "``$type $parameter``\n"; + print "``" . $parameter . "``\n"; output_highlight_rst($args{'parameterdescs'}{$parameter_name}); print "\n"; } @@ -2193,7 +2205,9 @@ sub dump_typedef($$) { $x =~ s@/\*.*?\*/@@gos; # strip comments. # Parse function prototypes - if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) { + if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ || + $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) { + # Function typedefs $return_type = $1; $declaration_name = $2; @@ -2204,6 +2218,7 @@ sub dump_typedef($$) { output_declaration($declaration_name, 'function', {'function' => $declaration_name, + 'typedef' => 1, 'module' => $modulename, 'functiontype' => $return_type, 'parameterlist' => \@parameterlist, @@ -2338,6 +2353,7 @@ sub push_parameter($$$) { if ($type eq "" && $param =~ /\.\.\.$/) { + $param = "..."; if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { $parameterdescs{$param} = "variable arguments"; } |