diff options
35 files changed, 603 insertions, 394 deletions
diff --git a/.gitignore b/.gitignore index f2f63e47fb88..bf5ee6e01cd4 100644 --- a/.gitignore +++ b/.gitignore @@ -40,6 +40,7 @@ *.o *.o.* *.patch +*.pyc *.rmeta *.rpm *.rsi diff --git a/Documentation/Makefile b/Documentation/Makefile index c022b97c487e..d30d66ddf1ad 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -60,9 +60,8 @@ endif #HAVE_LATEXMK # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -KERNELDOC = $(srctree)/scripts/kernel-doc.py -KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) -ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) +ALLSPHINXOPTS = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) +ALLSPHINXOPTS += $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) ifneq ($(wildcard $(srctree)/.config),) ifeq ($(CONFIG_RUST),y) # Let Sphinx know we will include rustdoc @@ -83,9 +82,11 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; # $5 reST source folder relative to $(src), # e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media +PYTHONPYCACHEPREFIX ?= $(abspath $(BUILDDIR)/__pycache__) + quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \ - PYTHONDONTWRITEBYTECODE=1 \ + PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(src)/$5/$(SPHINX_CONF)) \ $(PYTHON3) $(srctree)/scripts/jobserver-exec \ $(CONFIG_SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \ diff --git a/Documentation/admin-guide/namespaces/resource-control.rst b/Documentation/admin-guide/namespaces/resource-control.rst index 369556e00f0c..553a44803231 100644 --- a/Documentation/admin-guide/namespaces/resource-control.rst +++ b/Documentation/admin-guide/namespaces/resource-control.rst @@ -1,17 +1,17 @@ -=========================== -Namespaces research control -=========================== +==================================== +User namespaces and resource control +==================================== -There are a lot of kinds of objects in the kernel that don't have -individual limits or that have limits that are ineffective when a set -of processes is allowed to switch user ids. With user namespaces -enabled in a kernel for people who don't trust their users or their -users programs to play nice this problems becomes more acute. +The kernel contains many kinds of objects that either don't have +individual limits or that have limits which are ineffective when +a set of processes is allowed to switch their UID. On a system +where the admins don't trust their users or their users' programs, +user namespaces expose the system to potential misuse of resources. -Therefore it is recommended that memory control groups be enabled in -kernels that enable user namespaces, and it is further recommended -that userspace configure memory control groups to limit how much -memory user's they don't trust to play nice can use. +In order to mitigate this, we recommend that admins enable memory +control groups on any system that enables user namespaces. +Furthermore, we recommend that admins configure the memory control +groups to limit the maximum memory usable by any untrusted user. Memory control groups can be configured by installing the libcgroup package present on most distros editing /etc/cgrules.conf, diff --git a/Documentation/admin-guide/pm/cpufreq.rst b/Documentation/admin-guide/pm/cpufreq.rst index 3950583f2b15..2d74af7f0efe 100644 --- a/Documentation/admin-guide/pm/cpufreq.rst +++ b/Documentation/admin-guide/pm/cpufreq.rst @@ -231,7 +231,7 @@ are the following: present). The existence of the limit may be a result of some (often unintentional) - BIOS settings, restrictions coming from a service processor or another + BIOS settings, restrictions coming from a service processor or other BIOS/HW-based mechanisms. This does not cover ACPI thermal limitations which can be discovered @@ -258,8 +258,8 @@ are the following: extension on ARM). If one cannot be determined, this attribute should not be present. - Note, that failed attempt to retrieve current frequency for a given - CPU(s) will result in an appropriate error, i.e: EAGAIN for CPU that + Note that failed attempt to retrieve current frequency for a given + CPU(s) will result in an appropriate error, i.e.: EAGAIN for CPU that remains idle (raised on ARM). ``cpuinfo_max_freq`` @@ -499,7 +499,7 @@ This governor exposes the following tunables: represented by it to be 1.5 times as high as the transition latency (the default):: - # echo `$(($(cat cpuinfo_transition_latency) * 3 / 2)) > ondemand/sampling_rate + # echo `$(($(cat cpuinfo_transition_latency) * 3 / 2))` > ondemand/sampling_rate ``up_threshold`` If the estimated CPU load is above this value (in percent), the governor diff --git a/Documentation/admin-guide/quickly-build-trimmed-linux.rst b/Documentation/admin-guide/quickly-build-trimmed-linux.rst index 07cfd8863b46..4a5ffb0996a3 100644 --- a/Documentation/admin-guide/quickly-build-trimmed-linux.rst +++ b/Documentation/admin-guide/quickly-build-trimmed-linux.rst @@ -347,7 +347,7 @@ again. [:ref:`details<uninstall>`] -.. _submit_improvements: +.. _submit_improvements_qbtl: Did you run into trouble following any of the above steps that is not cleared up by the reference section below? Or do you have ideas how to improve the text? @@ -1070,7 +1070,7 @@ complicated, and harder to follow. That being said: this of course is a balancing act. Hence, if you think an additional use-case is worth describing, suggest it to the maintainers of this -document, as :ref:`described above <submit_improvements>`. +document, as :ref:`described above <submit_improvements_qbtl>`. .. diff --git a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst index 03c55151346c..d8946b084b1e 100644 --- a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst +++ b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst @@ -267,7 +267,7 @@ culprit might be known already. For further details on what actually qualifies as a regression check out Documentation/admin-guide/reporting-regressions.rst. If you run into any problems while following this guide or have ideas how to -improve it, :ref:`please let the kernel developers know <submit_improvements>`. +improve it, :ref:`please let the kernel developers know <submit_improvements_vbbr>`. .. _introprep_bissbs: @@ -1055,7 +1055,7 @@ follow these instructions. [:ref:`details <introoptional_bisref>`] -.. _submit_improvements: +.. _submit_improvements_vbbr: Conclusion ---------- diff --git a/Documentation/arch/x86/x86_64/fsgs.rst b/Documentation/arch/x86/x86_64/fsgs.rst index d07e445dac5c..6bda4d16d3f7 100644 --- a/Documentation/arch/x86/x86_64/fsgs.rst +++ b/Documentation/arch/x86/x86_64/fsgs.rst @@ -130,7 +130,7 @@ instructions. Clang 5 supports them as well. =================== =========================== _readfsbase_u64() Read the FS base register - _readfsbase_u64() Read the GS base register + _readgsbase_u64() Read the GS base register _writefsbase_u64() Write the FS base register _writegsbase_u64() Write the GS base register =================== =========================== diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst index 3085f8b460fa..8f0910668ca3 100644 --- a/Documentation/driver-api/dmaengine/provider.rst +++ b/Documentation/driver-api/dmaengine/provider.rst @@ -217,10 +217,12 @@ Currently, the types available are: - DMA_ASYNC_TX - - Must not be set by the device, and will be set by the framework - if needed + - The device supports asynchronous memory-to-memory operations, + including memcpy, memset, xor, pq, xor_val, and pq_val. - - TODO: What is it about? + - This capability is automatically set by the DMA engine + framework and must not be configured manually by device + drivers. - DMA_SLAVE diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index 89f9c37bb979..976fb4221062 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -161,6 +161,7 @@ rely on 64bit DMA to eliminate another kind of bounce buffer. .. kernel-doc:: drivers/usb/core/urb.c :export: +.. c:namespace:: usb_core .. kernel-doc:: drivers/usb/core/message.c :export: diff --git a/Documentation/hid/intel-thc-hid.rst b/Documentation/hid/intel-thc-hid.rst index 6c417205ac6a..dc9250787fc5 100644 --- a/Documentation/hid/intel-thc-hid.rst +++ b/Documentation/hid/intel-thc-hid.rst @@ -182,7 +182,7 @@ value and use PIO write (by setting SubIP write opcode) to do a write operation. THC also includes two GPIO pins, one for interrupt and the other for device reset control. -Interrupt line can be configured to either level triggerred or edge triggerred by setting MMIO +Interrupt line can be configured to either level triggered or edge triggered by setting MMIO Control register. Reset line is controlled by BIOS (or EFI) through ACPI _RST method, driver needs to call this @@ -302,10 +302,10 @@ waiting for interrupt ready then read out the data from system memory. 3.3.2 Software DMA channel ~~~~~~~~~~~~~~~~~~~~~~~~~~ -THC supports a software triggerred RxDMA mode to read the touch data from touch IC. This SW RxDMA +THC supports a software triggered RxDMA mode to read the touch data from touch IC. This SW RxDMA is the 3rd THC RxDMA engine with the similar functionalities as the existing two RxDMAs, the only -difference is this SW RxDMA is triggerred by software, and RxDMA2 is triggerred by external Touch IC -interrupt. It gives a flexiblity to software driver to use RxDMA read Touch IC data in any time. +difference is this SW RxDMA is triggered by software, and RxDMA2 is triggered by external Touch IC +interrupt. It gives a flexibility to software driver to use RxDMA read Touch IC data in any time. Before software starts a SW RxDMA, it shall stop the 1st and 2nd RxDMA, clear PRD read/write pointer and quiesce the device interrupt (THC_DEVINT_QUIESCE_HW_STS = 1), other operations are the same with diff --git a/Documentation/index.rst b/Documentation/index.rst index f9f525f4c0dd..c0cf79a87c3a 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -84,7 +84,7 @@ which are kept separately from the kernel's own documentation. Firmware-related documentation ============================== The following holds information on the kernel's expectations regarding the -platform firmwares. +platform firmware. .. toctree:: :maxdepth: 1 diff --git a/Documentation/leds/leds-class-multicolor.rst b/Documentation/leds/leds-class-multicolor.rst index c57b98bfd387..c6b47b4093c4 100644 --- a/Documentation/leds/leds-class-multicolor.rst +++ b/Documentation/leds/leds-class-multicolor.rst @@ -18,24 +18,28 @@ array. These files are children under the LED parent node created by the led_class framework. The led_class framework is documented in led-class.rst within this documentation directory. -Each colored LED will be indexed under the multi_* files. The order of the -colors will be arbitrary. The multi_index file can be read to determine the +Each colored LED will be indexed under the ``multi_*`` files. The order of the +colors will be arbitrary. The ``multi_index`` file can be read to determine the color name to indexed value. -The multi_index file is an array that contains the string list of the colors as -they are defined in each multi_* array file. +The ``multi_index`` file is an array that contains the string list of the colors as +they are defined in each ``multi_*`` array file. -The multi_intensity is an array that can be read or written to for the +The ``multi_intensity`` is an array that can be read or written to for the individual color intensities. All elements within this array must be written in order for the color LED intensities to be updated. Directory Layout Example ======================== -root:/sys/class/leds/multicolor:status# ls -lR --rw-r--r-- 1 root root 4096 Oct 19 16:16 brightness --r--r--r-- 1 root root 4096 Oct 19 16:16 max_brightness --r--r--r-- 1 root root 4096 Oct 19 16:16 multi_index --rw-r--r-- 1 root root 4096 Oct 19 16:16 multi_intensity +.. code-block:: console + + root:/sys/class/leds/multicolor:status# ls -lR + -rw-r--r-- 1 root root 4096 Oct 19 16:16 brightness + -r--r--r-- 1 root root 4096 Oct 19 16:16 max_brightness + -r--r--r-- 1 root root 4096 Oct 19 16:16 multi_index + -rw-r--r-- 1 root root 4096 Oct 19 16:16 multi_intensity + +.. Multicolor Class Brightness Control =================================== @@ -43,27 +47,31 @@ The brightness level for each LED is calculated based on the color LED intensity setting divided by the global max_brightness setting multiplied by the requested brightness. -led_brightness = brightness * multi_intensity/max_brightness +``led_brightness = brightness * multi_intensity/max_brightness`` Example: A user first writes the multi_intensity file with the brightness levels for each LED that are necessary to achieve a certain color output from a multicolor LED group. -cat /sys/class/leds/multicolor:status/multi_index -green blue red +.. code-block:: console + + # cat /sys/class/leds/multicolor:status/multi_index + green blue red -echo 43 226 138 > /sys/class/leds/multicolor:status/multi_intensity + # echo 43 226 138 > /sys/class/leds/multicolor:status/multi_intensity -red - - intensity = 138 - max_brightness = 255 -green - - intensity = 43 - max_brightness = 255 -blue - - intensity = 226 - max_brightness = 255 + red - + intensity = 138 + max_brightness = 255 + green - + intensity = 43 + max_brightness = 255 + blue - + intensity = 226 + max_brightness = 255 + +.. The user can control the brightness of that multicolor LED group by writing the global 'brightness' control. Assuming a max_brightness of 255 the user @@ -71,16 +79,28 @@ may want to dim the LED color group to half. The user would write a value of 128 to the global brightness file then the values written to each LED will be adjusted base on this value. -cat /sys/class/leds/multicolor:status/max_brightness -255 -echo 128 > /sys/class/leds/multicolor:status/brightness +.. code-block:: console + + # cat /sys/class/leds/multicolor:status/max_brightness + 255 + # echo 128 > /sys/class/leds/multicolor:status/brightness -adjusted_red_value = 128 * 138/255 = 69 -adjusted_green_value = 128 * 43/255 = 21 -adjusted_blue_value = 128 * 226/255 = 113 +.. + +.. code-block:: none + + adjusted_red_value = 128 * 138/255 = 69 + adjusted_green_value = 128 * 43/255 = 21 + adjusted_blue_value = 128 * 226/255 = 113 + +.. Reading the global brightness file will return the current brightness value of the color LED group. -cat /sys/class/leds/multicolor:status/brightness -128 +.. code-block:: console + + # cat /sys/class/leds/multicolor:status/brightness + 128 + +.. diff --git a/Documentation/process/1.Intro.rst b/Documentation/process/1.Intro.rst index c3d0270bbfb3..25ca49f7ae4d 100644 --- a/Documentation/process/1.Intro.rst +++ b/Documentation/process/1.Intro.rst @@ -251,12 +251,12 @@ there is no prospect of a migration to version 3 of the GPL in the foreseeable future. It is imperative that all code contributed to the kernel be legitimately -free software. For that reason, code from anonymous (or pseudonymous) -contributors will not be accepted. All contributors are required to "sign -off" on their code, stating that the code can be distributed with the -kernel under the GPL. Code which has not been licensed as free software by -its owner, or which risks creating copyright-related problems for the -kernel (such as code which derives from reverse-engineering efforts lacking +free software. For that reason, code from contributors without a known +identity or anonymous contributors will not be accepted. All contributors are +required to "sign off" on their code, stating that the code can be distributed +with the kernel under the GPL. Code which has not been licensed as free +software by its owner, or which risks creating copyright-related problems for +the kernel (such as code which derives from reverse-engineering efforts lacking proper safeguards) cannot be contributed. Questions about copyright-related issues are common on Linux development diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index ecf54d22e9dc..fd633f7a0bc3 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -128,13 +128,8 @@ def note_failure(target): # own C role, but both match the same regex, so we try both. # def markup_func_ref_sphinx3(docname, app, match): - cdom = app.env.domains['c'] - # - # Go through the dance of getting an xref out of the C domain - # base_target = match.group(2) target_text = nodes.Text(match.group(0)) - xref = None possible_targets = [base_target] # Check if this document has a namespace, and if so, try # cross-referencing inside it first. @@ -146,22 +141,8 @@ def markup_func_ref_sphinx3(docname, app, match): if (target not in Skipfuncs) and not failure_seen(target): lit_text = nodes.literal(classes=['xref', 'c', 'c-func']) lit_text += target_text - pxref = addnodes.pending_xref('', refdomain = 'c', - reftype = 'function', - reftarget = target, - modname = None, - classname = None) - # - # XXX The Latex builder will throw NoUri exceptions here, - # work around that by ignoring them. - # - try: - xref = cdom.resolve_xref(app.env, docname, app.builder, - 'function', target, pxref, - lit_text) - except NoUri: - xref = None - + xref = add_and_resolve_xref(app, docname, 'c', 'function', + target, contnode=lit_text) if xref: return xref note_failure(target) @@ -188,13 +169,8 @@ def markup_c_ref(docname, app, match): RE_typedef: 'type', } - cdom = app.env.domains['c'] - # - # Go through the dance of getting an xref out of the C domain - # base_target = match.group(2) target_text = nodes.Text(match.group(0)) - xref = None possible_targets = [base_target] # Check if this document has a namespace, and if so, try # cross-referencing inside it first. @@ -206,21 +182,9 @@ def markup_c_ref(docname, app, match): if not (match.re == RE_function and target in Skipfuncs): lit_text = nodes.literal(classes=['xref', 'c', class_str[match.re]]) lit_text += target_text - pxref = addnodes.pending_xref('', refdomain = 'c', - reftype = reftype_str[match.re], - reftarget = target, modname = None, - classname = None) - # - # XXX The Latex builder will throw NoUri exceptions here, - # work around that by ignoring them. - # - try: - xref = cdom.resolve_xref(app.env, docname, app.builder, - reftype_str[match.re], target, pxref, - lit_text) - except NoUri: - xref = None - + xref = add_and_resolve_xref(app, docname, 'c', + reftype_str[match.re], target, + contnode=lit_text) if xref: return xref @@ -231,30 +195,12 @@ def markup_c_ref(docname, app, match): # cross reference to that page # def markup_doc_ref(docname, app, match): - stddom = app.env.domains['std'] - # - # Go through the dance of getting an xref out of the std domain - # absolute = match.group(1) target = match.group(2) if absolute: target = "/" + target - xref = None - pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'doc', - reftarget = target, modname = None, - classname = None, refexplicit = False) - # - # XXX The Latex builder will throw NoUri exceptions here, - # work around that by ignoring them. - # - try: - xref = stddom.resolve_xref(app.env, docname, app.builder, 'doc', - target, pxref, None) - except NoUri: - xref = None - # - # Return the xref if we got it; otherwise just return the plain text. - # + + xref = add_and_resolve_xref(app, docname, 'std', 'doc', target) if xref: return xref else: @@ -265,10 +211,6 @@ def markup_doc_ref(docname, app, match): # with a cross reference to that page # def markup_abi_ref(docname, app, match, warning=False): - stddom = app.env.domains['std'] - # - # Go through the dance of getting an xref out of the std domain - # kernel_abi = get_kernel_abi() fname = match.group(1) @@ -280,7 +222,18 @@ def markup_abi_ref(docname, app, match, warning=False): kernel_abi.log.warning("%s not found", fname) return nodes.Text(match.group(0)) - pxref = addnodes.pending_xref('', refdomain = 'std', reftype = 'ref', + xref = add_and_resolve_xref(app, docname, 'std', 'ref', target) + if xref: + return xref + else: + return nodes.Text(match.group(0)) + +def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None): + # + # Go through the dance of getting an xref out of the corresponding domain + # + dom_obj = app.env.domains[domain] + pxref = addnodes.pending_xref('', refdomain = domain, reftype = reftype, reftarget = target, modname = None, classname = None, refexplicit = False) @@ -289,17 +242,15 @@ def markup_abi_ref(docname, app, match, warning=False): # work around that by ignoring them. # try: - xref = stddom.resolve_xref(app.env, docname, app.builder, 'ref', - target, pxref, None) + xref = dom_obj.resolve_xref(app.env, docname, app.builder, reftype, + target, pxref, contnode) except NoUri: xref = None - # - # Return the xref if we got it; otherwise just return the plain text. - # + if xref: return xref - else: - return nodes.Text(match.group(0)) + + return None # # Variant of markup_abi_ref() that warns whan a reference is not found diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 344789ed9ea2..b713a2c4a615 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -41,7 +41,15 @@ import sphinx from sphinx.util.docutils import switch_source_input from sphinx.util import logging +srctree = os.path.abspath(os.environ["srctree"]) +sys.path.insert(0, os.path.join(srctree, "scripts/lib/kdoc")) + +from kdoc_files import KernelFiles +from kdoc_output import RestFormat + __version__ = '1.0' +kfiles = None +logger = logging.getLogger('kerneldoc') def cmd_str(cmd): """ @@ -79,14 +87,34 @@ class KernelDocDirective(Directive): 'functions': directives.unchanged, } has_content = False - logger = logging.getLogger('kerneldoc') verbose = 0 - def run(self): + parse_args = {} + msg_args = {} + + def handle_args(self): + env = self.state.document.settings.env cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] + + # Arguments used by KernelFiles.parse() function + self.parse_args = { + "file_list": [filename], + "export_file": [] + } + + # Arguments used by KernelFiles.msg() function + self.msg_args = { + "enable_lineno": True, + "export": False, + "internal": False, + "symbol": [], + "nosymbol": [], + "no_doc_sections": False + } + export_file_patterns = [] verbose = os.environ.get("V") @@ -99,7 +127,8 @@ class KernelDocDirective(Directive): # 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) + self.tab_width = self.options.get('tab-width', + self.state.document.settings.tab_width) # 'function' is an alias of 'identifiers' if 'functions' in self.options: @@ -108,12 +137,16 @@ class KernelDocDirective(Directive): # FIXME: make this nicer and more robust against errors if 'export' in self.options: cmd += ['-export'] + self.msg_args["export"] = True export_file_patterns = str(self.options.get('export')).split() elif 'internal' in self.options: cmd += ['-internal'] + self.msg_args["internal"] = True export_file_patterns = str(self.options.get('internal')).split() elif 'doc' in self.options: - cmd += ['-function', str(self.options.get('doc'))] + func = str(self.options.get('doc')) + cmd += ['-function', func] + self.msg_args["symbol"].append(func) elif 'identifiers' in self.options: identifiers = self.options.get('identifiers').split() if identifiers: @@ -123,8 +156,10 @@ class KernelDocDirective(Directive): continue cmd += ['-function', i] + self.msg_args["symbol"].append(i) else: cmd += ['-no-doc-sections'] + self.msg_args["no_doc_sections"] = True if 'no-identifiers' in self.options: no_identifiers = self.options.get('no-identifiers').split() @@ -135,6 +170,7 @@ class KernelDocDirective(Directive): continue cmd += ['-nosymbol', i] + self.msg_args["nosymbol"].append(i) for pattern in export_file_patterns: pattern = pattern.rstrip("\\").strip() @@ -144,14 +180,31 @@ class KernelDocDirective(Directive): for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): env.note_dependency(os.path.abspath(f)) cmd += ['-export-file', f] + self.parse_args["export_file"].append(f) + + # Export file is needed by both parse and msg, as kernel-doc + # cache exports. + self.msg_args["export_file"] = self.parse_args["export_file"] cmd += [filename] + return cmd + + def run_cmd(self): + """ + Execute an external kernel-doc command. + """ + + env = self.state.document.settings.env + cmd = self.handle_args() + if self.verbose >= 1: print(cmd_str(cmd)) + node = nodes.section() + try: - self.logger.verbose("calling kernel-doc '%s'" % (" ".join(cmd))) + logger.verbose("calling kernel-doc '%s'" % (" ".join(cmd))) p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE) out, err = p.communicate() @@ -161,13 +214,35 @@ class KernelDocDirective(Directive): if p.returncode != 0: sys.stderr.write(err) - self.logger.warning("kernel-doc '%s' failed with return code %d" + logger.warning("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) + except Exception as e: # pylint: disable=W0703 + logger.warning("kernel-doc '%s' processing failed with: %s" % + (" ".join(cmd), str(e))) + return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + + filenames = self.parse_args["file_list"] + for filename in filenames: + ret = self.parse_msg(filename, node, out, cmd) + if ret: + return ret + + return node.children + + def parse_msg(self, filename, node, out, cmd): + """ + Handles a kernel-doc output for a given file + """ + + env = self.state.document.settings.env + + try: + lines = statemachine.string2lines(out, self.tab_width, + convert_whitespace=True) result = ViewList() lineoffset = 0; @@ -183,20 +258,64 @@ class KernelDocDirective(Directive): result.append(line, doc + ": " + filename, lineoffset) lineoffset += 1 - node = nodes.section() self.do_parse(result, node) - return node.children - except Exception as e: # pylint: disable=W0703 - self.logger.warning("kernel-doc '%s' processing failed with: %s" % - (" ".join(cmd), str(e))) + logger.warning("kernel-doc '%s' processing failed with: %s" % + (cmd_str(cmd), str(e))) return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + return None + + def run_kdoc(self, kfiles): + """ + Execute kernel-doc classes directly instead of running as a separate + command. + """ + + cmd = self.handle_args() + env = self.state.document.settings.env + + node = nodes.section() + + kfiles.parse(**self.parse_args) + filenames = self.parse_args["file_list"] + + for filename, out in kfiles.msg(**self.msg_args, filenames=filenames): + if self.verbose >= 1: + print(cmd_str(cmd)) + + ret = self.parse_msg(filename, node, out, cmd) + if ret: + return ret + + return node.children + + def run(self): + global kfiles + + if kfiles: + return self.run_kdoc(kfiles) + else: + return self.run_cmd() + def do_parse(self, result, node): with switch_source_input(self.state, result): self.state.nested_parse(result, 0, node, match_titles=1) +def setup_kfiles(app): + global kfiles + + kerneldoc_bin = app.env.config.kerneldoc_bin + + if kerneldoc_bin and kerneldoc_bin.endswith("kernel-doc.py"): + print("Using Python kernel-doc") + out_style = RestFormat() + kfiles = KernelFiles(out_style=out_style, logger=logger) + else: + print(f"Using {kerneldoc_bin}") + + def setup(app): app.add_config_value('kerneldoc_bin', None, 'env') app.add_config_value('kerneldoc_srctree', None, 'env') @@ -204,6 +323,8 @@ def setup(app): app.add_directive('kernel-doc', KernelDocDirective) + app.connect('builder-inited', setup_kfiles) + return dict( version = __version__, parallel_read_safe = True, diff --git a/Documentation/staging/speculation.rst b/Documentation/staging/speculation.rst index 8045d99bcf12..0d526ba55d14 100644 --- a/Documentation/staging/speculation.rst +++ b/Documentation/staging/speculation.rst @@ -63,7 +63,6 @@ of an out-of-bounds address, while the second call will influence microarchitectural state dependent on this value. This may provide an arbitrary read primitive. -==================================== Mitigating speculation side-channels ==================================== diff --git a/Documentation/tools/rtla/common_timerlat_description.rst b/Documentation/tools/rtla/common_timerlat_description.rst index 321201cb8597..49fcae3ffdec 100644 --- a/Documentation/tools/rtla/common_timerlat_description.rst +++ b/Documentation/tools/rtla/common_timerlat_description.rst @@ -6,5 +6,13 @@ debugging of operating system timer latency. The *timerlat* tracer outputs information in two ways. It periodically prints the timer latency at the timer *IRQ* handler and the *Thread* -handler. It also enable the trace of the most relevant information via +handler. It also enables the trace of the most relevant information via **osnoise:** tracepoints. + +The **rtla timerlat** tool sets the options of the *timerlat* tracer +and collects and displays a summary of the results. By default, +the collection is done synchronously in kernel space using a dedicated +BPF program attached to the *timerlat* tracer. If either BPF or +the **osnoise:timerlat_sample** tracepoint it attaches to is +unavailable, the **rtla timerlat** tool falls back to using tracefs to +process the data asynchronously in user space. diff --git a/Documentation/tools/rtla/rtla-timerlat.rst b/Documentation/tools/rtla/rtla-timerlat.rst index 44a49e6f302b..20e2d259467f 100644 --- a/Documentation/tools/rtla/rtla-timerlat.rst +++ b/Documentation/tools/rtla/rtla-timerlat.rst @@ -16,13 +16,10 @@ DESCRIPTION .. include:: common_timerlat_description.rst -The *timerlat* tracer outputs information in two ways. It periodically -prints the timer latency at the timer *IRQ* handler and the *Thread* handler. -It also provides information for each noise via the **osnoise:** tracepoints. The **rtla timerlat top** mode displays a summary of the periodic output -from the *timerlat* tracer. The **rtla hist hist** mode displays a histogram -of each tracer event occurrence. For further details, please refer to the -respective man page. +from the *timerlat* tracer. The **rtla timerlat hist** mode displays +a histogram of each tracer event occurrence. For further details, please +refer to the respective man page. MODES ===== diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst index 2c991dc96ace..cc1dc5a087e8 100644 --- a/Documentation/trace/index.rst +++ b/Documentation/trace/index.rst @@ -1,39 +1,103 @@ -========================== -Linux Tracing Technologies -========================== +================================ +Linux Tracing Technologies Guide +================================ + +Tracing in the Linux kernel is a powerful mechanism that allows +developers and system administrators to analyze and debug system +behavior. This guide provides documentation on various tracing +frameworks and tools available in the Linux kernel. + +Introduction to Tracing +----------------------- + +This section provides an overview of Linux tracing mechanisms +and debugging approaches. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - ftrace-design + debugging + tracepoints tracepoint-analysis + ring-buffer-map + +Core Tracing Frameworks +----------------------- + +The following are the primary tracing frameworks integrated into +the Linux kernel. + +.. toctree:: + :maxdepth: 1 + ftrace + ftrace-design ftrace-uses - fprobe kprobes kprobetrace - uprobetracer fprobetrace - tracepoints + fprobe + ring-buffer-design + +Event Tracing and Analysis +-------------------------- + +A detailed explanation of event tracing mechanisms and their +applications. + +.. toctree:: + :maxdepth: 1 + events events-kmem events-power events-nmi events-msr - mmiotrace + boottime-trace histogram histogram-design - boottime-trace - debugging - hwlat_detector - osnoise-tracer - timerlat-tracer + +Hardware and Performance Tracing +-------------------------------- + +This section covers tracing features that monitor hardware +interactions and system performance. + +.. toctree:: + :maxdepth: 1 + intel_th - ring-buffer-design - ring-buffer-map stm sys-t coresight/index - user_events rv/index hisi-ptt + mmiotrace + hwlat_detector + osnoise-tracer + timerlat-tracer + +User-Space Tracing +------------------ + +These tools allow tracing user-space applications and +interactions. + +.. toctree:: + :maxdepth: 1 + + user_events + uprobetracer + +Additional Resources +-------------------- + +For more details, refer to the respective documentation of each +tracing tool and framework. + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/sp_SP/process/2.Process.rst b/Documentation/translations/sp_SP/process/2.Process.rst index 5993eed71563..c21b0134cfa1 100644 --- a/Documentation/translations/sp_SP/process/2.Process.rst +++ b/Documentation/translations/sp_SP/process/2.Process.rst @@ -428,13 +428,14 @@ los desarrolladores, que corren el riesgo de quedar enterrados bajo una carga de correo electrónico, incumplir las convenciones utilizadas en las listas de Linux, o ambas cosas. -La mayoría de las listas de correo del kernel se ejecutan en -vger.kernel.org; la lista principal se puede encontrar en: +La mayoría de las listas de correo del kernel se alojan en kernel.org; la +lista principal se puede encontrar en: - http://vger.kernel.org/vger-lists.html + https://subspace.kernel.org -Sim embargo, hay listas alojadas en otros lugares; varios de ellos se -encuentran en redhat.com/mailman/listinfo. +Sin embargo, hay listas alojadas en otros lugares; consulte el archivo +MAINTAINERS para obtener la lista relevante para cualquier subsistema en +particular. La lista de correo principal para el desarrollo del kernel es, por supuesto, linux-kernel. Esta lista es un lugar intimidante; el volumen diff --git a/Documentation/translations/sp_SP/process/howto.rst b/Documentation/translations/sp_SP/process/howto.rst index 72ea855ac9dc..e1a6e6a52ae4 100644 --- a/Documentation/translations/sp_SP/process/howto.rst +++ b/Documentation/translations/sp_SP/process/howto.rst @@ -334,7 +334,7 @@ con el árbol principal, necesitan probar su integración. Para ello, existe un repositorio especial de pruebas en el que se encuentran casi todos los árboles de subsistema, actualizado casi a diario: - https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git + https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git De esta manera, linux-next ofrece una perspectiva resumida de lo que se espera que entre en el kernel principal en el próximo período de "merge" @@ -378,13 +378,13 @@ desarrolladores del kernel participan en la lista de correo del kernel de Linux. Detalles sobre cómo para suscribirse y darse de baja de la lista se pueden encontrar en: - http://vger.kernel.org/vger-lists.html#linux-kernel + https://subspace.kernel.org/subscribing.html Existen archivos de la lista de correo en la web en muchos lugares distintos. Utilice un motor de búsqueda para encontrar estos archivos. Por ejemplo: - http://dir.gmane.org/gmane.linux.kernel + https://lore.kernel.org/linux-kernel/ Es muy recomendable que busque en los archivos sobre el tema que desea tratar, antes de publicarlo en la lista. Un montón de cosas ya discutidas @@ -398,13 +398,13 @@ los diferentes grupos. Muchas de las listas están alojadas en kernel.org. La información sobre estas puede ser encontrada en: - http://vger.kernel.org/vger-lists.html + https://subspace.kernel.org Recuerde mantener buenos hábitos de comportamiento al usar las listas. Aunque un poco cursi, la siguiente URL tiene algunas pautas simples para interactuar con la lista (o cualquier lista): - http://www.albion.com/netiquette/ + https://subspace.kernel.org/etiquette.html Si varias personas responden a su correo, el CC (lista de destinatarios) puede hacerse bastante grande. No elimine a nadie de la lista CC: sin una diff --git a/Documentation/translations/sp_SP/process/kernel-docs.rst b/Documentation/translations/sp_SP/process/kernel-docs.rst index a62c6854f59b..b9e0ca4be324 100644 --- a/Documentation/translations/sp_SP/process/kernel-docs.rst +++ b/Documentation/translations/sp_SP/process/kernel-docs.rst @@ -170,9 +170,8 @@ Recursos varios * Título: **linux-kernel mailing list archives and search engines** - :URL: http://vger.kernel.org/vger-lists.html - :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html - :URL: http://groups.google.com/group/mlist.linux.kernel + :URL: https://subspace.kernel.org + :URL: https://lore.kernel.org :Palabras Clave: linux-kernel, archives, buscar, search, archivos. :Descripción: Algunos de los archivadores de listas de correo del kernel de Linux. Si usted tiene uno mejor/otro, por favor hágamelo diff --git a/Documentation/translations/sp_SP/process/submitting-patches.rst b/Documentation/translations/sp_SP/process/submitting-patches.rst index 328ec80bd61d..ecb08b14c2c0 100644 --- a/Documentation/translations/sp_SP/process/submitting-patches.rst +++ b/Documentation/translations/sp_SP/process/submitting-patches.rst @@ -136,11 +136,11 @@ algo documentado en la web, referencie esto. Cuando se vincule a archivos de listas de correo, preferiblemente use el servicio de archivador de mensajes lore.kernel.org. Para crear la URL del -enlace, utilice el contenido del encabezado ("header") ``Message-Id`` del +enlace, utilice el contenido del encabezado ("header") ``Message-ID`` del mensaje sin los corchetes angulares que lo rodean. Por ejemplo:: - Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI Verifique el enlace para asegurarse de que realmente funciona y apunta al mensaje correspondiente. @@ -257,10 +257,10 @@ archivo MAINTAINERS una lista específica de los subsistemas; su parche probablemente recibirá más atención allí. Sin embargo, no envíe spam a listas no relacionadas. -Muchas listas relacionadas con el kernel están alojadas en vger.kernel.org; +Muchas listas relacionadas con el kernel están alojadas en kernel.org; puedes encontrar un listado de estas en -http://vger.kernel.org/vger-lists.html. Existen listas relacionadas con el -kernel alojadas en otros lugares, no obstante. +https://subspace.kernel.org. Existen listas relacionadas con el kernel +alojadas en otros lugares, no obstante. ¡No envíe más de 15 parches a la vez a las listas de correo de vger! @@ -907,9 +907,6 @@ Referencias <http://www.kroah.com/log/linux/maintainer-06.html> -NO!!!! Gente, no mas bombas enormes de parches a linux-kernel@vger.kernel.org! - <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> - Kernel Documentation/process/coding-style.rst Email de Linus Torvalds sobre la forma canónica de los parches: diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 7a1409ecc238..83e5d2abdad6 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -28,10 +28,10 @@ or number from the table below. Because of the large number of drivers, many drivers share a partial letter with other drivers. If you are writing a driver for a new device and need a letter, pick an -unused block with enough room for expansion: 32 to 256 ioctl commands. -You can register the block by patching this file and submitting the -patch to Linus Torvalds. Or you can e-mail me at <mec@shout.net> and -I'll register one for you. +unused block with enough room for expansion: 32 to 256 ioctl commands +should suffice. You can register the block by patching this file and +submitting the patch through :doc:`usual patch submission process +</process/submitting-patches>`. The second argument to _IO, _IOW, _IOR, or _IOWR is a sequence number to distinguish ioctls from each other. The third argument to _IOW, @@ -458,6 +458,11 @@ endif HOSTRUSTC = rustc HOSTPKG_CONFIG = pkg-config +# the KERNELDOC macro needs to be exported, as scripts/Makefile.build +# has a logic to call it +KERNELDOC = $(srctree)/scripts/kernel-doc.py +export KERNELDOC + KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \ -O2 -fomit-frame-pointer -std=gnu11 KBUILD_USERCFLAGS := $(KBUILD_USERHOSTCFLAGS) $(USERCFLAGS) diff --git a/drivers/gpu/drm/Makefile b/drivers/gpu/drm/Makefile index ed54a546bbe2..d21d0cd2c752 100644 --- a/drivers/gpu/drm/Makefile +++ b/drivers/gpu/drm/Makefile @@ -236,7 +236,7 @@ always-$(CONFIG_DRM_HEADER_TEST) += \ quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@) cmd_hdrtest = \ $(CC) $(c_flags) -fsyntax-only -x c /dev/null -include $< -include $<; \ - $(srctree)/scripts/kernel-doc -none $(if $(CONFIG_WERROR)$(CONFIG_DRM_WERROR),-Werror) $<; \ + PYTHONDONTWRITEBYTECODE=1 $(KERNELDOC) -none $(if $(CONFIG_WERROR)$(CONFIG_DRM_WERROR),-Werror) $<; \ touch $@ $(obj)/%.hdrtest: $(src)/%.h FORCE diff --git a/drivers/gpu/drm/i915/Makefile b/drivers/gpu/drm/i915/Makefile index ed05b131ed3a..ab6b89a163e7 100644 --- a/drivers/gpu/drm/i915/Makefile +++ b/drivers/gpu/drm/i915/Makefile @@ -408,7 +408,7 @@ obj-$(CONFIG_DRM_I915_GVT_KVMGT) += kvmgt.o # # Enable locally for CONFIG_DRM_I915_WERROR=y. See also scripts/Makefile.build ifdef CONFIG_DRM_I915_WERROR - cmd_checkdoc = $(srctree)/scripts/kernel-doc -none -Werror $< + cmd_checkdoc = PYTHONDONTWRITEBYTECODE=1 $(KERNELDOC) -none -Werror $< endif # header test diff --git a/include/drm/Makefile b/include/drm/Makefile index a7bd15d2803e..1df6962556ef 100644 --- a/include/drm/Makefile +++ b/include/drm/Makefile @@ -11,7 +11,7 @@ always-$(CONFIG_DRM_HEADER_TEST) += \ quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@) cmd_hdrtest = \ $(CC) $(c_flags) -fsyntax-only -x c /dev/null -include $< -include $<; \ - $(srctree)/scripts/kernel-doc -none $(if $(CONFIG_WERROR)$(CONFIG_DRM_WERROR),-Werror) $<; \ + PYTHONDONTWRITEBYTECODE=1 $(KERNELDOC) -none $(if $(CONFIG_WERROR)$(CONFIG_DRM_WERROR),-Werror) $<; \ touch $@ $(obj)/%.hdrtest: $(src)/%.h FORCE diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 13dcd86e74ca..884dc86ce04e 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -83,7 +83,7 @@ else ifeq ($(KBUILD_CHECKSRC),2) endif ifneq ($(KBUILD_EXTRA_WARN),) - cmd_checkdoc = $(srctree)/scripts/kernel-doc -none $(KDOCFLAGS) \ + cmd_checkdoc = PYTHONDONTWRITEBYTECODE=1 $(KERNELDOC) -none $(KDOCFLAGS) \ $(if $(findstring 2, $(KBUILD_EXTRA_WARN)), -Wall) \ $< endif diff --git a/scripts/find-unused-docs.sh b/scripts/find-unused-docs.sh index ee6a50e33aba..d6d397fbf917 100755 --- a/scripts/find-unused-docs.sh +++ b/scripts/find-unused-docs.sh @@ -54,7 +54,7 @@ for file in `find $1 -name '*.c'`; do if [[ ${FILES_INCLUDED[$file]+_} ]]; then continue; fi - str=$(scripts/kernel-doc -export "$file" 2>/dev/null) + str=$(PYTHONDONTWRITEBYTECODE=1 scripts/kernel-doc -export "$file" 2>/dev/null) if [[ -n "$str" ]]; then echo "$file" fi diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py index dd003feefd1b..630aa5ca6460 100644 --- a/scripts/lib/kdoc/kdoc_files.py +++ b/scripts/lib/kdoc/kdoc_files.py @@ -250,6 +250,8 @@ class KernelFiles(): if not filenames: filenames = sorted(self.results.keys()) + glob = GlobSourceFiles(srctree=self.config.src_tree) + for fname in filenames: function_table = set() @@ -257,7 +259,7 @@ class KernelFiles(): if not export_file: export_file = [fname] - for f in export_file: + for f in glob.parse_files(export_file, self.file_not_found_cb): function_table |= self.export_table[f] if symbol: @@ -270,13 +272,16 @@ class KernelFiles(): msg = "" for name, arg in self.results[fname]: - msg += self.out_msg(fname, name, arg) + m = self.out_msg(fname, name, arg) - if msg is None: + if m is None: ln = arg.get("ln", 0) dtype = arg.get('type', "") self.config.log.warning("%s:%d Can't handle %s", fname, ln, dtype) + else: + msg += m + if msg: yield fname, msg diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output.py index 86102e628d91..86102e628d91 100755..100644 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py index 4f036c720b36..062453eefc7a 100755..100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -12,7 +12,6 @@ Read a C language source or header FILE and extract embedded documentation comments """ -import argparse import re from pprint import pformat @@ -61,24 +60,22 @@ export_symbol_ns = KernRe(r'^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*"\S+" type_param = KernRe(r"\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False) - -class KernelDoc: +class state: """ - Read a C language source or header FILE and extract embedded - documentation comments. + State machine enums """ # Parser states - STATE_NORMAL = 0 # normal code - STATE_NAME = 1 # looking for function name - STATE_BODY_MAYBE = 2 # body - or maybe more description - STATE_BODY = 3 # the body of the comment - STATE_BODY_WITH_BLANK_LINE = 4 # the body which has a blank line - STATE_PROTO = 5 # scanning prototype - STATE_DOCBLOCK = 6 # documentation block - STATE_INLINE = 7 # gathering doc outside main block - - st_name = [ + NORMAL = 0 # normal code + NAME = 1 # looking for function name + BODY_MAYBE = 2 # body - or maybe more description + BODY = 3 # the body of the comment + BODY_WITH_BLANK_LINE = 4 # the body which has a blank line + PROTO = 5 # scanning prototype + DOCBLOCK = 6 # documentation block + INLINE = 7 # gathering doc outside main block + + name = [ "NORMAL", "NAME", "BODY_MAYBE", @@ -90,15 +87,15 @@ class KernelDoc: ] # Inline documentation state - STATE_INLINE_NA = 0 # not applicable ($state != STATE_INLINE) - STATE_INLINE_NAME = 1 # looking for member name (@foo:) - STATE_INLINE_TEXT = 2 # looking for member documentation - STATE_INLINE_END = 3 # done - STATE_INLINE_ERROR = 4 # error - Comment without header was found. - # Spit a warning as it's not - # proper kernel-doc and ignore the rest. - - st_inline_name = [ + INLINE_NA = 0 # not applicable ($state != INLINE) + INLINE_NAME = 1 # looking for member name (@foo:) + INLINE_TEXT = 2 # looking for member documentation + INLINE_END = 3 # done + INLINE_ERROR = 4 # error - Comment without header was found. + # Spit a warning as it's not + # proper kernel-doc and ignore the rest. + + inline_name = [ "", "_NAME", "_TEXT", @@ -106,92 +103,149 @@ class KernelDoc: "_ERROR", ] - # Section names +SECTION_DEFAULT = "Description" # default section - section_default = "Description" # default section - section_intro = "Introduction" - section_context = "Context" - section_return = "Return" +class KernelEntry: - undescribed = "-- undescribed --" + def __init__(self, config, ln): + self.config = config - def __init__(self, config, fname): - """Initialize internal variables""" + self.contents = "" + self.function = "" + self.sectcheck = "" + self.struct_actual = "" + self.prototype = "" - self.fname = fname - self.config = config + self.warnings = [] - # Initial state for the state machines - self.state = self.STATE_NORMAL - self.inline_doc_state = self.STATE_INLINE_NA + self.parameterlist = [] + self.parameterdescs = {} + self.parametertypes = {} + self.parameterdesc_start_lines = {} - # Store entry currently being processed - self.entry = None + self.section_start_lines = {} + self.sectionlist = [] + self.sections = {} - # Place all potential outputs into an array - self.entries = [] + self.anon_struct_union = False + + self.leading_space = None + + # State flags + self.brcount = 0 + + self.in_doc_sect = False + self.declaration_start_line = ln + 1 # TODO: rename to emit_message after removal of kernel-doc.pl - def emit_warning(self, ln, msg, warning=True): + def emit_msg(self, log_msg, warning=True): """Emit a message""" - log_msg = f"{self.fname}:{ln} {msg}" - if not warning: self.config.log.info(log_msg) return - if self.entry: - # Delegate warning output to output logic, as this way it - # will report warnings/info only for symbols that are output + # Delegate warning output to output logic, as this way it + # will report warnings/info only for symbols that are output - self.entry.warnings.append(log_msg) - return - - self.config.log.warning(log_msg) + self.warnings.append(log_msg) + return def dump_section(self, start_new=True): """ Dumps section contents to arrays/hashes intended for that purpose. """ - name = self.entry.section - contents = self.entry.contents + name = self.section + contents = self.contents if type_param.match(name): name = type_param.group(1) - self.entry.parameterdescs[name] = contents - self.entry.parameterdesc_start_lines[name] = self.entry.new_start_line + self.parameterdescs[name] = contents + self.parameterdesc_start_lines[name] = self.new_start_line - self.entry.sectcheck += name + " " - self.entry.new_start_line = 0 + self.sectcheck += name + " " + self.new_start_line = 0 elif name == "@...": name = "..." - self.entry.parameterdescs[name] = contents - self.entry.sectcheck += name + " " - self.entry.parameterdesc_start_lines[name] = self.entry.new_start_line - self.entry.new_start_line = 0 + self.parameterdescs[name] = contents + self.sectcheck += name + " " + self.parameterdesc_start_lines[name] = self.new_start_line + self.new_start_line = 0 else: - if name in self.entry.sections and self.entry.sections[name] != "": + if name in self.sections and self.sections[name] != "": # Only warn on user-specified duplicate section names - if name != self.section_default: - self.emit_warning(self.entry.new_start_line, - f"duplicate section name '{name}'\n") - self.entry.sections[name] += contents + if name != SECTION_DEFAULT: + self.emit_msg(self.new_start_line, + f"duplicate section name '{name}'\n") + self.sections[name] += contents else: - self.entry.sections[name] = contents - self.entry.sectionlist.append(name) - self.entry.section_start_lines[name] = self.entry.new_start_line - self.entry.new_start_line = 0 + self.sections[name] = contents + self.sectionlist.append(name) + self.section_start_lines[name] = self.new_start_line + self.new_start_line = 0 -# self.config.log.debug("Section: %s : %s", name, pformat(vars(self.entry))) +# self.config.log.debug("Section: %s : %s", name, pformat(vars(self))) if start_new: - self.entry.section = self.section_default - self.entry.contents = "" + self.section = SECTION_DEFAULT + self.contents = "" + + +class KernelDoc: + """ + Read a C language source or header FILE and extract embedded + documentation comments. + """ + + # Section names + + section_intro = "Introduction" + section_context = "Context" + section_return = "Return" + + undescribed = "-- undescribed --" + + def __init__(self, config, fname): + """Initialize internal variables""" + + self.fname = fname + self.config = config + + # Initial state for the state machines + self.state = state.NORMAL + self.inline_doc_state = state.INLINE_NA + + # Store entry currently being processed + self.entry = None + + # Place all potential outputs into an array + self.entries = [] + + def emit_msg(self, ln, msg, warning=True): + """Emit a message""" + + log_msg = f"{self.fname}:{ln} {msg}" + + if self.entry: + self.entry.emit_msg(log_msg, warning) + return + + if warning: + self.config.log.warning(log_msg) + else: + self.config.log.info(log_msg) + + def dump_section(self, start_new=True): + """ + Dumps section contents to arrays/hashes intended for that purpose. + """ + + if self.entry: + self.entry.dump_section(start_new) # TODO: rename it to store_declaration after removal of kernel-doc.pl def output_declaration(self, dtype, name, **args): @@ -236,36 +290,11 @@ class KernelDoc: variables used by the state machine. """ - self.entry = argparse.Namespace - - self.entry.contents = "" - self.entry.function = "" - self.entry.sectcheck = "" - self.entry.struct_actual = "" - self.entry.prototype = "" - - self.entry.warnings = [] - - self.entry.parameterlist = [] - self.entry.parameterdescs = {} - self.entry.parametertypes = {} - self.entry.parameterdesc_start_lines = {} - - self.entry.section_start_lines = {} - self.entry.sectionlist = [] - self.entry.sections = {} - - self.entry.anon_struct_union = False - - self.entry.leading_space = None + self.entry = KernelEntry(self.config, ln) # State flags - self.state = self.STATE_NORMAL - self.inline_doc_state = self.STATE_INLINE_NA - self.entry.brcount = 0 - - self.entry.in_doc_sect = False - self.entry.declaration_start_line = ln + 1 + self.state = state.NORMAL + self.inline_doc_state = state.INLINE_NA def push_parameter(self, ln, decl_type, param, dtype, org_arg, declaration_name): @@ -323,8 +352,8 @@ class KernelDoc: else: dname = f"{decl_type} member" - self.emit_warning(ln, - f"{dname} '{param}' not described in '{declaration_name}'") + self.emit_msg(ln, + f"{dname} '{param}' not described in '{declaration_name}'") # Strip spaces from param so that it is one continuous string on # parameterlist. This fixes a problem where check_sections() @@ -388,7 +417,7 @@ class KernelDoc: if r.match(arg): param = r.group(1) else: - self.emit_warning(ln, f"Invalid param: {arg}") + self.emit_msg(ln, f"Invalid param: {arg}") param = arg dtype = KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).sub(r'\1', arg) @@ -404,7 +433,7 @@ class KernelDoc: if r.match(arg): param = r.group(1) else: - self.emit_warning(ln, f"Invalid param: {arg}") + self.emit_msg(ln, f"Invalid param: {arg}") param = arg dtype = KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).sub(r'\1', arg) @@ -437,7 +466,7 @@ class KernelDoc: if KernRe(r'^(\*+)\s*(.*)').match(param): r = KernRe(r'^(\*+)\s*(.*)') if not r.match(param): - self.emit_warning(ln, f"Invalid param: {param}") + self.emit_msg(ln, f"Invalid param: {param}") continue param = r.group(1) @@ -450,7 +479,7 @@ class KernelDoc: elif KernRe(r'(.*?):(\w+)').search(param): r = KernRe(r'(.*?):(\w+)') if not r.match(param): - self.emit_warning(ln, f"Invalid param: {param}") + self.emit_msg(ln, f"Invalid param: {param}") continue if dtype != "": # Skip unnamed bit-fields @@ -498,8 +527,8 @@ class KernelDoc: else: dname = f"{decl_type} member" - self.emit_warning(ln, - f"Excess {dname} '{sects[sx]}' description in '{decl_name}'") + self.emit_msg(ln, + f"Excess {dname} '{sects[sx]}' description in '{decl_name}'") def check_return_section(self, ln, declaration_name, return_type): """ @@ -516,8 +545,8 @@ class KernelDoc: return if not self.entry.sections.get("Return", None): - self.emit_warning(ln, - f"No description found for return value of '{declaration_name}'") + self.emit_msg(ln, + f"No description found for return value of '{declaration_name}'") def dump_struct(self, ln, proto): """ @@ -556,12 +585,12 @@ class KernelDoc: members = r.group(2) if not members: - self.emit_warning(ln, f"{proto} error: Cannot parse struct or union!") + self.emit_msg(ln, f"{proto} error: Cannot parse struct or union!") return if self.entry.identifier != declaration_name: - self.emit_warning(ln, - f"expecting prototype for {decl_type} {self.entry.identifier}. Prototype was for {decl_type} {declaration_name} instead\n") + self.emit_msg(ln, + f"expecting prototype for {decl_type} {self.entry.identifier}. Prototype was for {decl_type} {declaration_name} instead\n") return args_pattern = r'([^,)]+)' @@ -830,16 +859,16 @@ class KernelDoc: members = r.group(2).rstrip() if not members: - self.emit_warning(ln, f"{proto}: error: Cannot parse enum!") + self.emit_msg(ln, f"{proto}: error: Cannot parse enum!") return if self.entry.identifier != declaration_name: if self.entry.identifier == "": - self.emit_warning(ln, - f"{proto}: wrong kernel-doc identifier on prototype") + self.emit_msg(ln, + f"{proto}: wrong kernel-doc identifier on prototype") else: - self.emit_warning(ln, - f"expecting prototype for enum {self.entry.identifier}. Prototype was for enum {declaration_name} instead") + self.emit_msg(ln, + f"expecting prototype for enum {self.entry.identifier}. Prototype was for enum {declaration_name} instead") return if not declaration_name: @@ -856,14 +885,14 @@ class KernelDoc: self.entry.parameterlist.append(arg) if arg not in self.entry.parameterdescs: self.entry.parameterdescs[arg] = self.undescribed - self.emit_warning(ln, - f"Enum value '{arg}' not described in enum '{declaration_name}'") + self.emit_msg(ln, + f"Enum value '{arg}' not described in enum '{declaration_name}'") member_set.add(arg) for k in self.entry.parameterdescs: if k not in member_set: - self.emit_warning(ln, - f"Excess enum value '%{k}' description in '{declaration_name}'") + self.emit_msg(ln, + f"Excess enum value '%{k}' description in '{declaration_name}'") self.output_declaration('enum', declaration_name, enum=declaration_name, @@ -1018,13 +1047,13 @@ class KernelDoc: found = True break if not found: - self.emit_warning(ln, - f"cannot understand function prototype: '{prototype}'") + self.emit_msg(ln, + f"cannot understand function prototype: '{prototype}'") return if self.entry.identifier != declaration_name: - self.emit_warning(ln, - f"expecting prototype for {self.entry.identifier}(). Prototype was for {declaration_name}() instead") + self.emit_msg(ln, + f"expecting prototype for {self.entry.identifier}(). Prototype was for {declaration_name}() instead") return prms = " ".join(self.entry.parameterlist) @@ -1087,8 +1116,8 @@ class KernelDoc: args = r.group(3) if self.entry.identifier != declaration_name: - self.emit_warning(ln, - f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n") + self.emit_msg(ln, + f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n") return decl_type = 'function' @@ -1119,7 +1148,8 @@ class KernelDoc: declaration_name = r.group(1) if self.entry.identifier != declaration_name: - self.emit_warning(ln, f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n") + self.emit_msg(ln, + f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n") return self.output_declaration('typedef', declaration_name, @@ -1130,7 +1160,7 @@ class KernelDoc: purpose=self.entry.declaration_purpose) return - self.emit_warning(ln, "error: Cannot parse typedef!") + self.emit_msg(ln, "error: Cannot parse typedef!") @staticmethod def process_export(function_set, line): @@ -1166,7 +1196,7 @@ class KernelDoc: self.entry.in_doc_sect = False # next line is always the function name - self.state = self.STATE_NAME + self.state = state.NAME def process_name(self, ln, line): """ @@ -1182,7 +1212,7 @@ class KernelDoc: self.entry.section = doc_block.group(1) self.entry.identifier = self.entry.section - self.state = self.STATE_DOCBLOCK + self.state = state.DOCBLOCK return if doc_decl.search(line): @@ -1224,10 +1254,10 @@ class KernelDoc: self.entry.identifier = self.entry.identifier.strip(" ") - self.state = self.STATE_BODY + self.state = state.BODY # if there's no @param blocks need to set up default section here - self.entry.section = self.section_default + self.entry.section = SECTION_DEFAULT self.entry.new_start_line = ln + 1 r = KernRe("[-:](.*)") @@ -1238,44 +1268,44 @@ class KernelDoc: r = KernRe(r"\s+") self.entry.descr = r.sub(" ", self.entry.descr) self.entry.declaration_purpose = self.entry.descr - self.state = self.STATE_BODY_MAYBE + self.state = state.BODY_MAYBE else: self.entry.declaration_purpose = "" if not self.entry.is_kernel_comment: - self.emit_warning(ln, - f"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}") - self.state = self.STATE_NORMAL + self.emit_msg(ln, + f"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}") + self.state = state.NORMAL if not self.entry.declaration_purpose and self.config.wshort_desc: - self.emit_warning(ln, - f"missing initial short description on line:\n{line}") + self.emit_msg(ln, + f"missing initial short description on line:\n{line}") if not self.entry.identifier and self.entry.decl_type != "enum": - self.emit_warning(ln, - f"wrong kernel-doc identifier on line:\n{line}") - self.state = self.STATE_NORMAL + self.emit_msg(ln, + f"wrong kernel-doc identifier on line:\n{line}") + self.state = state.NORMAL if self.config.verbose: - self.emit_warning(ln, - f"Scanning doc for {self.entry.decl_type} {self.entry.identifier}", + self.emit_msg(ln, + f"Scanning doc for {self.entry.decl_type} {self.entry.identifier}", warning=False) return # Failed to find an identifier. Emit a warning - self.emit_warning(ln, f"Cannot find identifier on line:\n{line}") + self.emit_msg(ln, f"Cannot find identifier on line:\n{line}") def process_body(self, ln, line): """ STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment. """ - if self.state == self.STATE_BODY_WITH_BLANK_LINE: + if self.state == state.BODY_WITH_BLANK_LINE: r = KernRe(r"\s*\*\s?\S") if r.match(line): self.dump_section() - self.entry.section = self.section_default + self.entry.section = SECTION_DEFAULT self.entry.new_start_line = ln self.entry.contents = "" @@ -1311,7 +1341,7 @@ class KernelDoc: if self.entry.contents: self.entry.contents += "\n" - self.state = self.STATE_BODY + self.state = state.BODY return if doc_end.search(line): @@ -1320,12 +1350,12 @@ class KernelDoc: # Look for doc_com + <text> + doc_end: r = KernRe(r'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') if r.match(line): - self.emit_warning(ln, f"suspicious ending line: {line}") + self.emit_msg(ln, f"suspicious ending line: {line}") self.entry.prototype = "" self.entry.new_start_line = ln + 1 - self.state = self.STATE_PROTO + self.state = state.PROTO return if doc_content.search(line): @@ -1336,16 +1366,16 @@ class KernelDoc: self.dump_section() self.entry.new_start_line = ln - self.state = self.STATE_BODY + self.state = state.BODY else: - if self.entry.section != self.section_default: - self.state = self.STATE_BODY_WITH_BLANK_LINE + if self.entry.section != SECTION_DEFAULT: + self.state = state.BODY_WITH_BLANK_LINE else: - self.state = self.STATE_BODY + self.state = state.BODY self.entry.contents += "\n" - elif self.state == self.STATE_BODY_MAYBE: + elif self.state == state.BODY_MAYBE: # Continued declaration purpose self.entry.declaration_purpose = self.entry.declaration_purpose.rstrip() @@ -1383,12 +1413,12 @@ class KernelDoc: return # Unknown line, ignore - self.emit_warning(ln, f"bad line: {line}") + self.emit_msg(ln, f"bad line: {line}") def process_inline(self, ln, line): """STATE_INLINE: docbook comments within a prototype.""" - if self.inline_doc_state == self.STATE_INLINE_NAME and \ + if self.inline_doc_state == state.INLINE_NAME and \ doc_inline_sect.search(line): self.entry.section = doc_inline_sect.group(1) self.entry.new_start_line = ln @@ -1397,7 +1427,7 @@ class KernelDoc: if self.entry.contents != "": self.entry.contents += "\n" - self.inline_doc_state = self.STATE_INLINE_TEXT + self.inline_doc_state = state.INLINE_TEXT # Documentation block end */ return @@ -1405,21 +1435,21 @@ class KernelDoc: if self.entry.contents not in ["", "\n"]: self.dump_section() - self.state = self.STATE_PROTO - self.inline_doc_state = self.STATE_INLINE_NA + self.state = state.PROTO + self.inline_doc_state = state.INLINE_NA return if doc_content.search(line): - if self.inline_doc_state == self.STATE_INLINE_TEXT: + if self.inline_doc_state == state.INLINE_TEXT: self.entry.contents += doc_content.group(1) + "\n" if not self.entry.contents.strip(" ").rstrip("\n"): self.entry.contents = "" - elif self.inline_doc_state == self.STATE_INLINE_NAME: - self.emit_warning(ln, - f"Incorrect use of kernel-doc format: {line}") + elif self.inline_doc_state == state.INLINE_NAME: + self.emit_msg(ln, + f"Incorrect use of kernel-doc format: {line}") - self.inline_doc_state = self.STATE_INLINE_ERROR + self.inline_doc_state = state.INLINE_ERROR def syscall_munge(self, ln, proto): # pylint: disable=W0613 """ @@ -1489,8 +1519,8 @@ class KernelDoc: tracepointargs = r.group(1) if not tracepointname or not tracepointargs: - self.emit_warning(ln, - f"Unrecognized tracepoint format:\n{proto}\n") + self.emit_msg(ln, + f"Unrecognized tracepoint format:\n{proto}\n") else: proto = f"static inline void trace_{tracepointname}({tracepointargs})" self.entry.identifier = f"trace_{self.entry.identifier}" @@ -1598,8 +1628,8 @@ class KernelDoc: self.dump_section(start_new=False) elif doc_inline_start.search(line): - self.state = self.STATE_INLINE - self.inline_doc_state = self.STATE_INLINE_NAME + self.state = state.INLINE + self.inline_doc_state = state.INLINE_NAME elif self.entry.decl_type == 'function': self.process_proto_function(ln, line) @@ -1663,7 +1693,7 @@ class KernelDoc: line = line.expandtabs().strip("\n") # Group continuation lines on prototypes - if self.state == self.STATE_PROTO: + if self.state == state.PROTO: if line.endswith("\\"): prev += line.rstrip("\\") cont = True @@ -1681,8 +1711,8 @@ class KernelDoc: prev_ln = None self.config.log.debug("%d %s%s: %s", - ln, self.st_name[self.state], - self.st_inline_name[self.inline_doc_state], + ln, state.name[self.state], + state.inline_name[self.inline_doc_state], line) # This is an optimization over the original script. @@ -1696,18 +1726,18 @@ class KernelDoc: self.process_export(export_table, line) # Hand this line to the appropriate state handler - if self.state == self.STATE_NORMAL: + if self.state == state.NORMAL: self.process_normal(ln, line) - elif self.state == self.STATE_NAME: + elif self.state == state.NAME: self.process_name(ln, line) - elif self.state in [self.STATE_BODY, self.STATE_BODY_MAYBE, - self.STATE_BODY_WITH_BLANK_LINE]: + elif self.state in [state.BODY, state.BODY_MAYBE, + state.BODY_WITH_BLANK_LINE]: self.process_body(ln, line) - elif self.state == self.STATE_INLINE: # scanning for inline parameters + elif self.state == state.INLINE: # scanning for inline parameters self.process_inline(ln, line) - elif self.state == self.STATE_PROTO: + elif self.state == state.PROTO: self.process_proto(ln, line) - elif self.state == self.STATE_DOCBLOCK: + elif self.state == state.DOCBLOCK: self.process_docblock(ln, line) except OSError: self.config.log.error(f"Error: Cannot open file {self.fname}") diff --git a/scripts/lib/kdoc/kdoc_re.py b/scripts/lib/kdoc/kdoc_re.py index e81695b273bf..e81695b273bf 100755..100644 --- a/scripts/lib/kdoc/kdoc_re.py +++ b/scripts/lib/kdoc/kdoc_re.py diff --git a/tools/tracing/rtla/README.txt b/tools/tracing/rtla/README.txt index dd5621038c55..43e98311d10f 100644 --- a/tools/tracing/rtla/README.txt +++ b/tools/tracing/rtla/README.txt @@ -13,6 +13,13 @@ RTLA depends on the following libraries and tools: - libtraceevent - libcpupower (optional, for --deepest-idle-state) +For BPF sample collection support, the following extra dependencies are +required: + + - libbpf 1.0.0 or later + - bpftool with skeleton support + - clang with BPF CO-RE support + It also depends on python3-docutils to compile man pages. For development, we suggest the following steps for compiling rtla: |