Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
5.1 kB · 173 lines
Python
at master
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174# -*- coding: utf-8; mode: python -*-# coding=utf-8# SPDX-License-Identifier: GPL-2.0#""" kernel-abi ~~~~~~~~~~
Implementation of the ``kernel-abi`` reST-directive.
:copyright: Copyright (C) 2016 Markus Heiser :copyright: Copyright (C) 2016-2020 Mauro Carvalho Chehab :maintained-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> :license: GPL Version 2, June 1991 see Linux/COPYING for details.
The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the AbiParser class to parse the Kernel ABI files.
Overview of directive's argument and options.
.. code-block:: rst
.. kernel-abi:: <ABI directory location> :debug:
The argument ``<ABI directory location>`` is required. It contains the location of the ABI files to be parsed.
``debug`` Inserts a code-block with the *raw* reST. Sometimes it is helpful to see what reST is generated.
"""
import osimport reimport sys
from docutils import nodes, statemachinefrom docutils.statemachine import ViewListfrom docutils.parsers.rst import directives, Directivefrom sphinx.util.docutils import switch_source_inputfrom sphinx.util import logging
srctree = os.path.abspath(os.environ["srctree"])sys.path.insert(0, os.path.join(srctree, "tools/lib/python"))
from abi.abi_parser import AbiParser
__version__ = "1.0"
logger = logging.getLogger('kernel_abi')path = os.path.join(srctree, "Documentation/ABI")
_kernel_abi = None
def get_kernel_abi(): """ Initialize kernel_abi global var, if not initialized yet.
This is needed to avoid warnings during Sphinx module initialization. """ global _kernel_abi
if not _kernel_abi: # Parse ABI symbols only once _kernel_abi = AbiParser(path, logger=logger) _kernel_abi.parse_abi() _kernel_abi.check_issues()
return _kernel_abi
def setup(app):
app.add_directive("kernel-abi", KernelCmd) return { "version": __version__, "parallel_read_safe": True, "parallel_write_safe": True }
class KernelCmd(Directive): """KernelABI (``kernel-abi``) directive"""
required_arguments = 1 optional_arguments = 3 has_content = False final_argument_whitespace = True parser = None
option_spec = { "debug": directives.flag, "no-symbols": directives.flag, "no-files": directives.flag, }
def run(self): kernel_abi = get_kernel_abi()
doc = self.state.document if not doc.settings.file_insertion_enabled: raise self.warning("docutils: file insertion disabled")
env = self.state.document.settings.env content = ViewList() node = nodes.section()
abi_type = self.arguments[0]
if "no-symbols" in self.options: show_symbols = False else: show_symbols = True
if "no-files" in self.options: show_file = False else: show_file = True
tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)
old_f = None n = 0 n_sym = 0 for msg, f, ln in kernel_abi.doc(show_file=show_file, show_symbols=show_symbols, filter_path=abi_type): n_sym += 1 msg_list = statemachine.string2lines(msg, tab_width, convert_whitespace=True) if "debug" in self.options: lines = [ "", "", ".. code-block:: rst", " :linenos:", "" ] for m in msg_list: lines.append(" " + m) else: lines = msg_list
for line in lines: # sphinx counts lines from 0 content.append(line, f, ln - 1) n += 1
if f != old_f: # Add the file to Sphinx build dependencies if the file exists fname = os.path.join(srctree, f) if os.path.isfile(fname): env.note_dependency(fname)
old_f = f
# Sphinx doesn't like to parse big messages. So, let's # add content symbol by symbol if content: self.do_parse(content, node) content = ViewList()
if show_symbols and not show_file: logger.verbose("%s ABI: %i symbols (%i ReST lines)" % (abi_type, n_sym, n)) elif not show_symbols and show_file: logger.verbose("%s ABI: %i files (%i ReST lines)" % (abi_type, n_sym, n)) else: logger.verbose("%s ABI: %i data (%i ReST lines)" % (abi_type, n_sym, n))
return node.children
def do_parse(self, content, node): with switch_source_input(self.state, content): self.state.nested_parse(content, 0, node, match_titles=1)