Eric Lee / smarc-fsl-linux-kernel

25 Feb, 2020

1 commit

  • adc10f5b0   docs: Fix empty parallelism argument ... Browse Code »

    When there was no parallelism (no top-level -j arg and a pre-1.7
    sphinx-build), the argument passed would be empty ("") instead of just
    being missing, which would (understandably) badly confuse sphinx-build.
    Fix this by removing the quotes.

    Reported-by: Rafael J. Wysocki
    Fixes: 51e46c7a4007 ("docs, parallelism: Rearrange how jobserver reservations are made")
    Cc: stable@vger.kernel.org # v5.5 only
    Signed-off-by: Kees Cook
    Signed-off-by: Jonathan Corbet

    Kees Cook
     

25 Jan, 2020

1 commit

  • bcac386f3   docs: Keep up with the location of NoUri ... Browse Code »

    Sphinx 2.1 moved sphinx.environment.NoUri into sphinx.errors; that produced
    this warning in the docs build:

    /usr/lib/python3.7/site-packages/sphinx/registry.py:473:
    RemovedInSphinx30Warning: sphinx.environment.NoUri is deprecated.

    Grab NoUri from the right place and make the warning go away. That symbol
    was only added to sphinx.errors in 2.1, so we must still import it from the
    old location when running in older versions.

    Signed-off-by: Jonathan Corbet

    Jonathan Corbet
     

23 Nov, 2019

1 commit

  • 51e46c7a4   docs, parallelism: Rearrange how jobserver reservations are made ... Browse Code »

    Rasmus correctly observed that the existing jobserver reservation only
    worked if no other build targets were specified. The correct approach
    is to hold the jobserver slots until sphinx has finished. To fix this,
    the following changes are made:

    - refactor (and rename) scripts/jobserver-exec to set an environment
    variable for the maximally reserved jobserver slots and exec a
    child, to release the slots on exit.

    - create Documentation/scripts/parallel-wrapper.sh which examines both
    $PARALLELISM and the detected "-jauto" logic from Documentation/Makefile
    to decide sphinx's final -j argument.

    - chain these together in Documentation/Makefile

    Suggested-by: Rasmus Villemoes
    Link: https://lore.kernel.org/lkml/eb25959a-9ec4-3530-2031-d9d716b40b20@rasmusvillemoes.dk
    Signed-off-by: Kees Cook
    Link: https://lore.kernel.org/r/20191121205929.40371-4-keescook@chromium.org
    Signed-off-by: Jonathan Corbet

    Kees Cook
     

08 Nov, 2019

1 commit

03 Oct, 2019

1 commit

  • aa2048552   doc-rst: Programmatically render MAINTAINERS into ReST ... Browse Code »

    In order to have the MAINTAINERS file visible in the rendered ReST
    output, this makes some small changes to the existing MAINTAINERS file
    to allow for better machine processing, and adds a new Sphinx directive
    "maintainers-include" to perform the rendering.

    Features include:
    - Per-subsystem reference links: subsystem maintainer entries can be
    trivially linked to both internally and external. For example:
    https://www.kernel.org/doc/html/latest/process/maintainers.html#secure-computing

    - Internally referenced .rst files are linked so they can be followed
    when browsing the resulting rendering. This allows, for example, the
    future addition of maintainer profiles to be automatically linked.

    - Field name expansion: instead of the short fields (e.g. "M", "F",
    "K"), use the indicated inline "full names" for the fields (which are
    marked with "*"s in MAINTAINERS) so that a rendered subsystem entry
    is more human readable. Email lists are additionally comma-separated.
    For example:

    SECURE COMPUTING
    Mail: Kees Cook
    Reviewer: Andy Lutomirski ,
    Will Drewry
    SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git seccomp
    Status: Supported
    Files: kernel/seccomp.c include/uapi/linux/seccomp.h
    include/linux/seccomp.h tools/testing/selftests/seccomp/*
    tools/testing/selftests/kselftest_harness.h
    userspace-api/seccomp_filter
    Content regex: \bsecure_computing \bTIF_SECCOMP\b

    Signed-off-by: Kees Cook
    Signed-off-by: Jonathan Corbet

    Kees Cook
     

13 Aug, 2019

2 commits

  • 82bf829b6   Documentation: sphinx: Don't parse socket() as identifier reference ... Browse Code »

    With the introduction of Documentation/sphinx/automarkup.py, socket() is
    parsed as a reference to the in-kernel definition of socket. Sphinx then
    decides that struct socket is a good match, which is usually not
    intended, when the syscall is meant instead. This was observed in
    Documentation/networking/af_xdp.rst.

    Prevent socket() from being misinterpreted by adding it to the Skipfuncs
    list in automarkup.py.

    Signed-off-by: Jonathan Neuschäfer
    Reviewed-by: Mauro Carvalho Chehab
    Signed-off-by: Jonathan Corbet

    Jonathan Neuschäfer
     
  • 11fec009d   Documentation: sphinx: Add missing comma to list of strings ... Browse Code »

    In Python, like in C, when a comma is omitted in a list of strings, the
    two strings around the missing comma are concatenated.

    Cc: stable@vger.kernel.org # v5.2 only
    Signed-off-by: Jonathan Neuschäfer
    Reviewed-by: Mauro Carvalho Chehab
    Signed-off-by: Jonathan Corbet

    Jonathan Neuschäfer
     

19 Jul, 2019

1 commit

17 Jul, 2019

1 commit

  • a84d9e899   docs: load_config.py: avoid needing a conf.py just due to LaTeX docs ... Browse Code »

    Right now, for every directory that we need to have LaTeX output,
    a conf.py file is required.

    That causes an extra overhead and it is actually a hack, as
    the latex_documents line there are usually a copy of the ones
    that are there already at the main conf.py.

    So, instead, re-use the global latex_documents var, just
    adjusting the path to be relative ones.

    Signed-off-by: Mauro Carvalho Chehab

    Mauro Carvalho Chehab
     

09 Jul, 2019

1 commit

  • 454f96f2b   docs: automarkup.py: ignore exceptions when seeking for xrefs ... Browse Code »

    When using the automarkup extension with:
    make pdfdocs

    without passing an specific book, the code will raise an exception:

    File "/devel/v4l/docs/Documentation/sphinx/automarkup.py", line 86, in auto_markup
    node.parent.replace(node, markup_funcs(name, app, node))
    File "/devel/v4l/docs/Documentation/sphinx/automarkup.py", line 59, in markup_funcs
    'function', target, pxref, lit_text)
    File "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/domains/c.py", line 308, in resolve_xref
    contnode, target)
    File "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/util/nodes.py", line 450, in make_refnode
    '#' + targetid)
    File "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/builders/latex/__init__.py", line 159, in get_relative_uri
    return self.get_target_uri(to, typ)
    File "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/builders/latex/__init__.py", line 152, in get_target_uri
    raise NoUri
    sphinx.environment.NoUri

    This happens because not all references will belong to a single
    PDF/LaTeX document.

    Better to just ignore those than breaking Sphinx build.

    Fixes: d74b0d31ddde ("Docs: An initial automarkup extension for sphinx")
    Signed-off-by: Mauro Carvalho Chehab
    [jc: Narrowed the "except" and tweaked the comment]
    Signed-off-by: Jonathan Corbet

    Mauro Carvalho Chehab
     

27 Jun, 2019

1 commit

31 May, 2019

1 commit

  • a700767a7   docs: requirements.txt: recommend Sphinx 1.7.9 ... Browse Code »

    As discussed at the linux-doc ML, while we'll still support
    version 1.3, it is time to recommend a more modern version.

    So, let's switch the minimal requirements to Sphinx 1.7.9,
    as it has the "-jauto" flag, with makes a lot faster when
    building documentation.

    Signed-off-by: Mauro Carvalho Chehab
    Signed-off-by: Jonathan Corbet

    Mauro Carvalho Chehab
     

30 May, 2019

1 commit

23 May, 2019

2 commits

  • 2404dad1f   doc: Cope with the deprecation of AutoReporter ... Browse Code »

    AutoReporter is going away; recent versions of sphinx emit a warning like:

    Documentation/sphinx/kerneldoc.py:125:
    RemovedInSphinx20Warning: AutodocReporter is now deprecated.
    Use sphinx.util.docutils.switch_source_input() instead.

    Make the switch. But switch_source_input() only showed up in 1.7, so we
    have to do ugly version checks to keep things working in older versions.

    Cc: stable@vger.kernel.org
    Signed-off-by: Jonathan Corbet

    Jonathan Corbet
     
  • 096ea522e   doc: Cope with Sphinx logging deprecations ... Browse Code »

    Recent versions of sphinx will emit messages like:

    Documentation/sphinx/kerneldoc.py:103:
    RemovedInSphinx20Warning: app.warning() is now deprecated.
    Use sphinx.util.logging instead.

    Switch to sphinx.util.logging to make this unsightly message go away.
    Alas, that interface was only added in version 1.6, so we have to add a
    version check to keep things working with older sphinxes.

    Cc: stable@vger.kernel.org
    Signed-off-by: Jonathan Corbet

    Jonathan Corbet
     

30 Jun, 2018

1 commit

  • f2e860360   Documentation/sphinx: allow "functions" with no parameters ... Browse Code »

    When kernel-doc:: specified in .rst document without explicit directives,
    it outputs both comment and DOC: sections. If a DOC: section was explicitly
    included in the same document it will be duplicated. For example, the
    output generated for Documentation/core-api/idr.rst [1] has "IDA
    description" in the "IDA usage" section and in the middle of the API
    reference.

    This patch enables using "functions" directive without parameters to output
    all the documentation excluding DOC: sections.

    [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html

    Signed-off-by: Mike Rapoport
    Acked-by: Matthew Wilcox
    Signed-off-by: Jonathan Corbet

    Mike Rapoport
     

26 Jun, 2018

1 commit

  • f3821276f   doc:sphinx: fix parse-header description ... Browse Code »

    The description speaks about the option ``--man`` but it
    does not exist. Instead, there is the option ``--usage``

    $ ./Documentation/sphinx/parse-headers.pl --man
    Unknown option: man
    Usage:
    parse_headers.pl [] []

    Where can be: --debug, --help or --man.

    Signed-off-by: Federico Vaga
    Signed-off-by: Jonathan Corbet

    Federico Vaga
     

16 Jun, 2018

1 commit

04 May, 2018

1 commit

  • 325908199   MAINTAINERS & files: Canonize the e-mails I use at files ... Browse Code »

    From now on, I'll start using my @kernel.org as my development e-mail.

    As such, let's remove the entries that point to the old
    mchehab@s-opensource.com at MAINTAINERS file.

    For the files written with a copyright with mchehab@s-opensource,
    let's keep Samsung on their names, using mchehab+samsung@kernel.org,
    in order to keep pointing to my employer, with sponsors the work.

    For the files written before I join Samsung (on July, 4 2013),
    let's just use mchehab@kernel.org.

    For bug reports, we can simply point to just kernel.org, as
    this will reach my mchehab+samsung inbox anyway.

    Signed-off-by: Mauro Carvalho Chehab
    Signed-off-by: Brian Warner
    Signed-off-by: Mauro Carvalho Chehab

    Mauro Carvalho Chehab
     

10 Mar, 2018

1 commit

  • ff690eeed   Documentation/sphinx: Fix Directive import error ... Browse Code »

    Sphinx 1.7 removed sphinx.util.compat.Directive so people
    who have upgraded cannot build the documentation. Switch to
    docutils.parsers.rst.Directive which has been available since
    docutils 0.5 released in 2009.

    Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694
    Co-developed-by: Takashi Iwai
    Acked-by: Jani Nikula
    Cc: stable@vger.kernel.org
    Signed-off-by: Matthew Wilcox
    Signed-off-by: Jonathan Corbet

    Matthew Wilcox
     

18 Jan, 2018

1 commit

01 Sep, 2017

1 commit

  • 86c0f046a   Documentation/sphinx: fix kernel-doc decode for non-utf-8 locale ... Browse Code »

    On python3, Popen() universal_newlines=True converts the subprocess
    stdout to unicode text using a codec based on user preferences. Given
    LANG indicating ascii and utf-8 stdout from the subprocess, you'd get:

    WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno
    ../drivers/media/dvb-core/demux.h' processing failed with: 'ascii' codec can't
    decode byte 0xe2 in position 6368: ordinal not in range(128)

    Fix this by dropping universal_newlines=True and replacing the implicit
    LANG specific decode with an explicit utf-8 decode. This also gets rid
    of the annoying conditional code for python 2 vs. 3.

    Fixes: ba3501859354 ("Documentation/sphinx: fix kernel-doc extension on python3")
    Reference: http://mid.mail-archive.com/54c23e8e-89c0-5cea-0dcc-e938952c5642@infradead.org
    Reported-and-tested-by: Randy Dunlap
    Cc: Jonathan Corbet
    Cc: Mauro Carvalho Chehab
    Signed-off-by: Jani Nikula
    Signed-off-by: Jonathan Corbet

    Jani Nikula
     

24 Jul, 2017

1 commit

24 Jun, 2017

1 commit

16 May, 2017

1 commit

12 Apr, 2017

1 commit

  • 686b0d9bb   tmplcvt: make the tool more robust ... Browse Code »

    Currently, the script just assumes to be called at
    Documentation/sphinx/. Change it to work on any directory,
    and make it abort if something gets wrong.

    Also, be sure that both parameters are specified.

    That should avoid troubles like this:

    $ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
    sed: couldn't open file convert_template.sed: No such file or directory

    Signed-off-by: Mauro Carvalho Chehab
    Signed-off-by: Jonathan Corbet

    Mauro Carvalho Chehab
     

31 Mar, 2017

1 commit

09 Mar, 2017

1 commit

  • db6ccf23e   docs-rst: automatically convert Graphviz and SVG images ... Browse Code »

    This patch brings scalable figure, image handling and a concept to
    embed *render* markups:

    * DOT (http://www.graphviz.org)
    * SVG

    For image handling use the 'image' replacement::

    .. kernel-image:: svg_image.svg
    :alt: simple SVG image

    For figure handling use the 'figure' replacement::

    .. kernel-figure:: svg_image.svg
    :alt: simple SVG image

    SVG image example

    Embed *render* markups (or languages) like Graphviz's **DOT** is
    provided by the *render* directive.::

    .. kernel-render:: DOT
    :alt: foobar digraph
    :caption: Embedded **DOT** (Graphviz) code.

    digraph foo {
    "bar" -> "baz";
    }

    The *render* directive is a concept to integrate *render* markups and
    languages, yet supported markups:

    * DOT: render embedded Graphviz's **DOT**
    * SVG: render embedded Scalable Vector Graphics (**SVG**)

    Cc: Jani Nikula
    Cc: Laurent Pinchart
    Tested-by: Mauro Carvalho Chehab
    Tested-by: Daniel Vetter
    Signed-off-by: Daniel Vetter (v2 - v5)
    Signed-off-by: Markus Heiser (v1, v6)
    Signed-off-by: Jonathan Corbet

    Markus Heiser
     

19 Dec, 2016

1 commit

  • 217e2bfab   docs: sphinx-extensions: make rstFlatTable work with docutils 0.13 ... Browse Code »

    In docutils 0.13, the return type of get_column_widths method of the
    Table directive has changed [1], which breaks our flat-table directive
    and leads to a TypeError when trying to build the docs [2].

    This patch adds support for the new return type, while keeping support
    for older docutils versions too.

    [1] https://sourceforge.net/p/docutils/patches/120/
    [2] https://sourceforge.net/p/docutils/bugs/303/

    Signed-off-by: Dmitry Shachnev
    Cc: # 4.8.x-
    Signed-off-by: Jonathan Corbet

    Dmitry Shachnev
     

01 Dec, 2016

1 commit

  • c33966566   docs-rst: parse-headers.pl: cleanup the documentation ... Browse Code »

    Keeping both rst and in-file documentation in sync can be harsh.

    So, simplify the script's internal documntation to a bare minimum,
    and add a mention to the ReST file with its full documentation.

    This way, a quick help is still available at the command line,
    while the complete one is maintained at the ReST format.

    As we won't be using pad2rst anymore, do a cleanup at the ReST
    file.

    Signed-off-by: Mauro Carvalho Chehab
    Signed-off-by: Jonathan Corbet

    Mauro Carvalho Chehab
     

20 Nov, 2016

1 commit

20 Oct, 2016

1 commit

20 Sep, 2016

1 commit

  • 142a0e11b   Merge tag 'docs-next' of git://git.lwn.net/linux.git into patchwork ... Browse Code »

    Merge back from docs-next in order to get the cdomain extension.

    With such extension, the number of warnings when building docs
    in nitpick mode reduced from 22 to 2 warnings.

    * docs-next/docs-next:
    docs/driver-model: fix typo
    DMA-API-HOWTO: is no more
    doc-rst:c-domain: function-like macros arguments
    doc-rst:c-domain: fix sphinx version incompatibility
    Documentation/filesystems: Fixed typo
    docs: Don't format internal MPT docs
    docs: split up serial-interfaces.rst
    docs: Pull the HSI documentation together
    docs: Special-case function-pointer parameters in kernel-doc
    docs: make kernel-doc handle varargs properly
    x86: fix memory ranges in mm documentation
    documentation/scsi: Remove nodisconnect parameter
    doc: ioctl: Add some clarifications to botching-up-ioctls
    docs: split up the driver book
    Docs: sphinxify device-drivers.tmpl

    Mauro Carvalho Chehab
     

16 Sep, 2016

2 commits

09 Sep, 2016

2 commits

01 Sep, 2016

1 commit

  • b62b9d81a   docs: sphinx-extensions: add metadata parallel-safe ... Browse Code »

    The setup() function of a Sphinx-extension can return a dictionary. This
    is treated by Sphinx as metadata of the extension [1].

    With metadata "parallel_read_safe = True" a extension is marked as
    save for "parallel reading of source". This is needed if you want
    build in parallel with N processes. E.g.:

    make SPHINXOPTS=-j4 htmldocs

    will no longer log warnings like:

    WARNING: the foobar extension does not declare if it is safe for
    parallel reading, assuming it isn't - please ask the extension author
    to check and make it explicit.

    Add metadata to extensions:

    * kernel-doc
    * flat-table
    * kernel-include

    [1] http://www.sphinx-doc.org/en/stable/extdev/#extension-metadata

    Signed-off-by: Markus Heiser
    Tested-by: Mauro Carvalho Chehab
    Signed-off-by: Jonathan Corbet

    Markus Heiser
     

23 Aug, 2016

2 commits

  • 556aa6d5d   doc-rst: moved *duplicate* warnings to nitpicky mode ... Browse Code »

    Moved the *duplicate C object description* warnings for function
    declarations in the nitpicky mode. In nitpick mode, you can suppress
    those warnings (e.g. ioctl) with::

    nitpicky = True
    nitpick_ignore = [
    ("c:func", "ioctl"),
    ]

    See Sphinx documentation for the config values for ``nitpick`` and
    ``nitpick_ignore`` [1].

    With this change all the ".. cpp:function:: int ioctl(..)" descriptions
    (found in the media book) can be migrated to ".. c:function:: int
    ioctl(..)", without getting any warnings. E.g.::

    .. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp )

    .. c:function:: int ioctl( int fd, int request, struct cec_event *argp )

    The main effect, is that we get those *CPP-types* back into Sphinx's C-
    namespace and we need no longer to distinguish between c/cpp references,
    when we refer a function like the ioctl.

    [1] http://www.sphinx-doc.org/en/stable/config.html?highlight=nitpick#confval-nitpicky

    Signed-off-by: Markus Heiser
    Signed-off-by: Jonathan Corbet

    Markus Heiser
     
  • 2c645cd7c   doc-rst:c-domain: ref-name of a function declaration ... Browse Code »

    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 index entry for
    this function is also changed to ``VIDIOC_LOG_STATUS`` and the function
    can now referenced by::

    :c:func:`VIDIOC_LOG_STATUS`

    Signed-off-by: Markus Heiser
    Signed-off-by: Jonathan Corbet

    Markus Heiser