xref: /linux/Documentation/sphinx/kernel_abi.py (revision a4eb44a6435d6d8f9e642407a4a06f65eb90ca04) 
1# -*- coding: utf-8; mode: python -*-
2# coding=utf-8
3# SPDX-License-Identifier: GPL-2.0
4#
5u"""
6    kernel-abi
7    ~~~~~~~~~~
8
9    Implementation of the ``kernel-abi`` reST-directive.
10
11    :copyright:  Copyright (C) 2016  Markus Heiser
12    :copyright:  Copyright (C) 2016-2020  Mauro Carvalho Chehab
13    :maintained-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
14    :license:    GPL Version 2, June 1991 see Linux/COPYING for details.
15
16    The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the
17    scripts/get_abi.pl script to parse the Kernel ABI files.
18
19    Overview of directive's argument and options.
20
21    .. code-block:: rst
22
23        .. kernel-abi:: <ABI directory location>
24            :debug:
25
26    The argument ``<ABI directory location>`` is required. It contains the
27    location of the ABI files to be parsed.
28
29    ``debug``
30      Inserts a code-block with the *raw* reST. Sometimes it is helpful to see
31      what reST is generated.
32
33"""
34
35import codecs
36import os
37import subprocess
38import sys
39import re
40import kernellog
41
42from os import path
43
44from docutils import nodes, statemachine
45from docutils.statemachine import ViewList
46from docutils.parsers.rst import directives, Directive
47from docutils.utils.error_reporting import ErrorString
48from sphinx.util.docutils import switch_source_input
49
50__version__  = '1.0'
51
52def setup(app):
53
54    app.add_directive("kernel-abi", KernelCmd)
55    return dict(
56        version = __version__
57        , parallel_read_safe = True
58        , parallel_write_safe = True
59    )
60
61class KernelCmd(Directive):
62
63    u"""KernelABI (``kernel-abi``) directive"""
64
65    required_arguments = 1
66    optional_arguments = 2
67    has_content = False
68    final_argument_whitespace = True
69
70    option_spec = {
71        "debug"     : directives.flag,
72        "rst"       : directives.unchanged
73    }
74
75    def run(self):
76
77        doc = self.state.document
78        if not doc.settings.file_insertion_enabled:
79            raise self.warning("docutils: file insertion disabled")
80
81        env = doc.settings.env
82        cwd = path.dirname(doc.current_source)
83        cmd = "get_abi.pl rest --enable-lineno --dir "
84        cmd += self.arguments[0]
85
86        if 'rst' in self.options:
87            cmd += " --rst-source"
88
89        srctree = path.abspath(os.environ["srctree"])
90
91        fname = cmd
92
93        # extend PATH with $(srctree)/scripts
94        path_env = os.pathsep.join([
95            srctree + os.sep + "scripts",
96            os.environ["PATH"]
97        ])
98        shell_env = os.environ.copy()
99        shell_env["PATH"]    = path_env
100        shell_env["srctree"] = srctree
101
102        lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env)
103        nodeList = self.nestedParse(lines, self.arguments[0])
104        return nodeList
105
106    def runCmd(self, cmd, **kwargs):
107        u"""Run command ``cmd`` and return its stdout as unicode."""
108
109        try:
110            proc = subprocess.Popen(
111                cmd
112                , stdout = subprocess.PIPE
113                , stderr = subprocess.PIPE
114                , **kwargs
115            )
116            out, err = proc.communicate()
117
118            out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
119
120            if proc.returncode != 0:
121                raise self.severe(
122                    u"command '%s' failed with return code %d"
123                    % (cmd, proc.returncode)
124                )
125        except OSError as exc:
126            raise self.severe(u"problems with '%s' directive: %s."
127                              % (self.name, ErrorString(exc)))
128        return out
129
130    def nestedParse(self, lines, fname):
131        content = ViewList()
132        node = nodes.section()
133
134        if "debug" in self.options:
135            code_block = "\n\n.. code-block:: rst\n    :linenos:\n"
136            for l in lines.split("\n"):
137                code_block += "\n    " + l
138            lines = code_block + "\n\n"
139
140        line_regex = re.compile("^#define LINENO (\S+)\#([0-9]+)$")
141        ln = 0
142        n = 0
143        f = fname
144
145        for line in lines.split("\n"):
146            n = n + 1
147            match = line_regex.search(line)
148            if match:
149                new_f = match.group(1)
150
151                # Sphinx parser is lazy: it stops parsing contents in the
152                # middle, if it is too big. So, handle it per input file
153                if new_f != f and content:
154                    self.do_parse(content, node)
155                    content = ViewList()
156
157                f = new_f
158
159                # sphinx counts lines from 0
160                ln = int(match.group(2)) - 1
161            else:
162                content.append(line, f, ln)
163
164        kernellog.info(self.state.document.settings.env.app, "%s: parsed %i lines" % (fname, n))
165
166        if content:
167            self.do_parse(content, node)
168
169        return node.children
170
171    def do_parse(self, content, node):
172        with switch_source_input(self.state, content):
173            self.state.nested_parse(content, 0, node, match_titles=1)
174